Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / MODEMPRO / ICOM201C.ZIP;1 / SCRTUTOR.DOC < prev next >

Wrap

Text File | 1994-06-06 | 235.0 KB | 4,805 lines

Intellicomm (TM) v2.01 Copyright (C) 1991-1994 Liberation Enterprises. All rights reserved. --------------------------------------------------------------------- INTELLICOMM SCRIPT LANGUAGE TUTORIAL --------------------------------------------------------------------- TABLE OF CONTENTS 1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 What are Scripts? . . . . . . . . . . . . . . . . . . . . . 1 1.2 Why Should I Bother With Scripts? . . . . . . . . . . . . . 1 1.3 Is This Going to Take HOURS? . . . . . . . . . . . . . . . . 2 1.4 Script Learn Mode . . . . . . . . . . . . . . . . . . . . . 2 1.5 How Do I Create a Script? . . . . . . . . . . . . . . . . . 3 1.6 Icom's Internal Editor vs. an External Editor . . . . . . . 4 1.7 Stopping Scripts . . . . . . . . . . . . . . . . . . . . . . 4 1.8 Creating and Running Your First Script . . . . . . . . . . . 5 1.9 A More Exciting Example . . . . . . . . . . . . . . . . . . 6 1.10 Other Ways of Running Scripts . . . . . . . . . . . . . . . 8 1.10.1 Running Script from BIFs (8); 1.10.2 Running Scripts from Jobs (8); 1.10.3 Running Scripts from DOS (9); 1.10.4 Running Scripts from Scripts (9); 1.10.5 Running Scripts from the Script Manager (9); 1.10.6 Running Scripts via Function Keys (10) 1.11 It Can't be That Simple, Can It? . . . . . . . . . . . . 10 1.12 Variable Overview . . . . . . . . . . . . . . . . . . . . 15 1.13 A Word on Formatting . . . . . . . . . . . . . . . . . . 18 1.14 Why the Double Quotes ""? . . . . . . . . . . . . . . . . 19 1.15 Specifying Control Characters . . . . . . . . . . . . . . 19 1.16 Tildes . . . . . . . . . . . . . . . . . . . . . . . . . 20 1.17 Specifying Numbers . . . . . . . . . . . . . . . . . . . 20 1.18 Numeric Limits . . . . . . . . . . . . . . . . . . . . . 21 1.19 Compound Statements . . . . . . . . . . . . . . . . . . . 21 1.20 Where To Go From Here . . . . . . . . . . . . . . . . . . 23 1.21 The Secret to Success . . . . . . . . . . . . . . . . . . 24 2. WHAT HAPPENS WHEN A SCRIPT ENDS? . . . . . . . . . . . . . . . 26 2.1 EXIT and RETURN Error codes . . . . . . . . . . . . . . . 27 2.2 Using the HANGUP Command for Error-Recovery . . . . . . . 28 3. INTRODUCTION TO SUBROUTINES (GOSUB) . . . . . . . . . . . . . . 28 3.1 When to use a Subroutine . . . . . . . . . . . . . . . . . 28 3.2 Writing a Subroutine . . . . . . . . . . . . . . . . . . . 29 3.3 GOSUB In Detail . . . . . . . . . . . . . . . . . . . . . 30 3.4 Creating a Subroutine Template . . . . . . . . . . . . . . 31 4. SCRIPT VARIABLES IN DETAIL . . . . . . . . . . . . . . . . . . 32 4.1 Why Would I Want to Use Variables? . . . . . . . . . . . . 32 4.2 Where you CAN'T use Variables . . . . . . . . . . . . . . 32 4.3 User-Defined Variables . . . . . . . . . . . . . . . . . . 32 4.4 User-Defined Variable Rules . . . . . . . . . . . . . . . 33 4.5 Why All the Rules? . . . . . . . . . . . . . . . . . . . . 35 4.6 Using Variables . . . . . . . . . . . . . . . . . . . . . 36 4.7 The Life of a Variable . . . . . . . . . . . . . . . . . . 37 4.8 Global Variables . . . . . . . . . . . . . . . . . . . . . 38 Intellicomm v2.01 SCRTUTOR.DOC ii 4.9 Using Global Variables . . . . . . . . . . . . . . . . . . 40 4.10 Passing Parameters to Scripts . . . . . . . . . . . . . . 41 4.11 Checking the Number of Passed Parameters . . . . . . . . 43 4.12 System Variables . . . . . . . . . . . . . . . . . . . . 44 4.13 BIF Variables . . . . . . . . . . . . . . . . . . . . . . 45 4.14 Main Setup and Environment Variables . . . . . . . . . . 45 4.15 Environment Variables . . . . . . . . . . . . . . . . . . 45 5. PERMANENT VARIABLES: INTRODUCTION TO FILE INPUT/OUTPUT . . . . 46 5.1 FOPEN 'Modes' . . . . . . . . . . . . . . . . . . . . . . 47 5.2 The File Handle . . . . . . . . . . . . . . . . . . . . . 48 5.3 Testing for End-of-File . . . . . . . . . . . . . . . . 53 5.4 How to store settings on-disk . . . . . . . . . . . . . . 53 5.5 Moving the File Pointer (Advanced Use Only) . . . . . . . 54 5.6 Opening a File for Reading AND Writing (Advanced use only) 57 5.7 Upating an Old Data File . . . . . . . . . . . . . . . . . 59 6. INTRODUCTION TO DATABASE COMMANDS (FILE TAGGER CATALOGS) . . . 62 6.1 Why would I want to use the catalog-oriented commands? . . 62 6.2 What is a Database? . . . . . . . . . . . . . . . . . . . 62 6.3 Indexes . . . . . . . . . . . . . . . . . . . . . . . . . 63 6.4 Using File Tagger Indexes . . . . . . . . . . . . . . . . 64 6.5 How this all applies to Scripts . . . . . . . . . . . . . 65 6.6 The View Date . . . . . . . . . . . . . . . . . . . . . . 70 6.7 Getting Around in a Catalog . . . . . . . . . . . . . . . 71 6.8 Getting the Total Number of Records . . . . . . . . . . . 72 6.9 The View Date and Tagged/Noted Files . . . . . . . . . . . 73 7. USING THE SCRIPT DEBUGGER . . . . . . . . . . . . . . . . . . . 74 7.1 What are BUGS, and What is a DEBUGGER? . . . . . . . . . . 74 7.2 Using the Debugger . . . . . . . . . . . . . . . . . . . . 75 7.3 Checking the Contents of a Single Variable . . . . . . . . 77 7.4 Debug Hotkeys . . . . . . . . . . . . . . . . . . . . . . 78 Intellicomm v2.01 SCRTUTOR.DOC 1 1. INTRODUCTION 1.1 What are Scripts? Scripts are files which contain one or more instructions (commands) for Intellicomm to carry out. You can't 'talk' to Intellicomm to tell it what to do when you have custom work to do (at least, not to my knowledge... <grin>), so the next best thing is to write it down and let Intellicomm read it. As a movie script tells the cast what to say and do: Intellicomm scripts tell Intellicomm what to say and do. You're the script writer and Intellicomm is your cast. Don't confuse scripts with Icom's automated jobs and BIFs. The jobs you run from the Job Directory and set up in the Job Editor are not scripts; they're called Jobs and they are carried out by ICOM.EXE's built-in automated routines, using BBS Information File (BIF) data. Jobs are jobs, BIFs are BIFs, and scripts are scripts. They're three different things, and this document discusses scripts only. For information on Icom's internal jobs (automated file uploads and downloads, mail transfers and time bank transactions, etc.) please refer to the online help, and particularly to "BIF Learn". 1.2 Why Should I Bother With Scripts? There are limitless benefits awaiting those who learn some (or all) of Intellicomm's script language, and learn the simple process of creating scripts. Most importantly, you will gain an incredibly flexible and powerful tool to add to your automation arsenal. Virtually ANYTHING you can dream up can be automated with a script, while BIFs and automated jobs (aside from the job "Custom Commands" which allow limited custom work) were designed for specific tasks. With scripts you can automate *any* BBS task by watching for specific text from the BBS and handling it as you see fit (send responses to the BBS, transfer files, display information on the screen, and do any number of other things). If desired, you can easily define your own custom interfaces using menus and other interactive functions for interactive user input, you can display multiple boxes/windows and other text on the screen (including the ability to display incoming text from the *BBS* in a window) using a bevy of powerful video-oriented script commands, you can run other DOS programs (or .BAT files, or other Icom scripts), pause script execution until a specific time and/or day, create, display, and otherwise maintain File Tagger catalogs in every way imagineable, read from and write to text files on-disk (save information permanently), display text files in the File Viewer or load them into the Editor for the user to view/modify, test for certain system conditions (date, time, day-of-week, etc.), get and set BIF and Icom main setup information, create 'keyboard macros', and on and on. Those who gain control over both Icom's built-in jobs AND its script language (and script learn mode, for registered users) truly have the most powerful and flexible set of tools available for automated BBS communications, probably anywhere in the universe. If automation, and Intellicomm v2.01 SCRTUTOR.DOC 2 taking the drudgery out of your online sessions is your passion, you can't beat that prospect! 1.3 Is This Going to Take HOURS? Don't be discouraged by the size of the script manuals. The script language and manuals are like a big bowl of peanuts: take what you want. You don't have to eat the whole bowl to enjoy yourself and get something useful done, and you'll be able to write very useful scripts after reading just the next few pages below. If you just want the basics, and the basics are VERY powerful and useful indeed, you should be finished in half-an-hour or less. If you end up drooling at the possibilities and want the whole bowl of peanuts, it'll take some practice (and some more reading) to get the whole language down. But it's your choice, and making progress and getting things DONE is a quick process as you'll soon see. You don't even have to print this document if you don't have the time or paper: Just read it in the help system ("SCRTUTOR.DOC" link; make sure SCRTUTOR.DOC is in the same directory as ICOM.EXE) or text viewer (via the Icom File Manager / "View" option) until you're satisfied with what you've learned. The script documents should be used as follows: 1. Read the introductory material in this document until you're happy with what you've learned. This document gives you the basics and, more importantly, shows you how to put script commands together to get something practical done. 2. Once you've got the basics down, use the "SCRIPT COMMANDS AT A GLANCE" section at the beginning of SCRIPT.DOC to find the command(s) you're interested in, and to refresh your memory as to what various commands do. 3. When you find the command you want, using step 2 above, look it up in the DETAILED COMMAND SUMMARY (sorted alphabetically by script command) in SCRIPT.DOC to quickly get all the details along with an EXAMPLE showing how to use the command. TIP: If you view SCRIPT.DOC from Icom's internal File Viewer or help system, to locate a command summary press [Alt-F] (Find) then type the command you're interested in, follow that with an underscore (e.g. PRINT_) then carry out the search DOWNWARDS to find the Detailed Summary in a flash. All commands in the Detailed Command Summary of SCRIPT.DOC are followed by a line of underscores to allow you to find commands quickly. The Table of Contents, and the index at the back of the manuals can also be used to locate information quickly. Many people skip the Table of Contents, but you can learn a lot by looking at it carefully. You'll see how the manuals are laid out, and more importantly can quickly see every major topic that is covered -- which can be useful to know when you have a question later. 1.4 Script Learn Mode The easiest way to become acquainted with scripts is to use Icom's script Intellicomm v2.01 SCRTUTOR.DOC 3 learn mode (a bonus feature in the registered version). With script learn mode you simply turn it on, then just 'do' whatever it is you want automated. Icom watches what you do and writes a script for you! Not only do you save time getting your scripts written, but it's also quite educational: by looking at the script Icom creates, you can learn how the script language works. Script Learn is accessed through the "Learn Modes" option of the Main Menu or Job Directory or Terminal "Tools" menu, and in various other places. Pressing [Alt-Q] from just about anywhere in Intellicomm calls up the Learn Modes menu. Use of Script Learn is quite straightforward, and is covered in the online help if you have questions. 1.5 How Do I Create a Script? Writing a script (or modifying/adding to one started with Script Learn) is much the same as typing a letter in your word processor. Instead of using a word processor though, which places printer commands and formatting codes all over the document, you instead use a "Text Editor" to create scripts. Text Editors work similarly to word processors as far as typing, deleting, cutting/pasting text, etc. But they don't add printer codes to the files you save to disk -- and they usually don't force margins on you, which is essential for writing scripts. Script command lines will sometimes be longer than your screen width, and thus the margins in word processors which 'wrap' long lines are not acceptable. The files Text Editors produce are called "text files", or "ASCII files" and these are the types of files Icom requires for scripts -- without any printer formatting codes or margins. Intellicomm comes with a built-in Text Editor, though you can use your favorite external Text Editor if you like (details in a second). For script writing, the editor (whether internal or external) is best accessed through the Icom "Script Manager". By accessing the Script Manager first you can be sure that your scripts will be saved in the proper directory; since Icom changes DOS to the Script Directory (\ICOM\SCR by default) when you enter the Script Manager. From the editor you just save your scripts in the current directory (without specifying a drive letter or \DIRECTORY\ name), and they always end up in the right place, where Icom expects them to be. The Script Manager can be accessed from the Icom Main Menu (and at various other menus), or by simply pressing [Alt-U] from just about anywhere in Intellicomm. [Sorry about the 'U'; it doesn't help much in remembering the key, but unfortunately [Alt-S] (S for Script) is a fairly standard 'Screen Capture' command and is used by the Terminal.] Once in the Script Manager, select "Create" from the bottom menu to create a new script, or hilight the script of interest and select "Edit" to view/modify an existing script, or hilight a script and select "Run" to execute it (the other options in the Script Manager are fairly self- Intellicomm v2.01 SCRTUTOR.DOC 4 explanatory... please see the online help if you need more information). There are several scripts included with Intellicomm for demonstration and other purposes. You can enter the Script Manager, hilight and "Run" SCRDEMO.SCR from the Script Manager now if you want to see a script in action before you continue reading. SCRDEMO.SCR can also be viewed after you run it, for many useful examples. Note that Intellicomm itself doesn't use SCRDEMO.SCR for anything, so you can delete the file when you're done with it, if you're short on disk space. 1.6 Icom's Internal Editor vs. an External Editor If you use Icom's internal Text Editor, you gain the advantage of online script writing help (online access to the documentation). So, when you forget one of the script commands we'll be discussing below you can simply press the [F1] help key, and call up the index of script help. You can view this document (if installed in the \ICOM directory) or SCRIPT.DOC to obtain any information you require, without leaving the editor by accessing the SCRTUTOR.DOC or SCRIPT.DOC help links (available from the "Script Language" Index, and various other places). A further advantage of using the internal editor is that if by chance you make a typing mistake in your script, then Run the script before noticing the error; Icom will be able to load the script into the internal editor, position the cursor right on the line of the script where the error occurred, displaying the error message to you so you can fix it. With an external editor Icom will still call your editor if an error is found, and if your editor accepts a filename on the command line the script will be loaded for you, but you won't be moved to the proper line number. You can get the error message (which includes the number of the line on which the error occurred) from the file \ICOM\SCRIPT.ERR while in your external editor, but unless you're proficient with your external editor and are used to doing this sort of thing (with other script languages or program compilers), you're probably better off using Icom's internal editor for the time being. To use an external editor you must define the editor command in the Icom main setup (accessed via the main menu "Intellicomm Setup" option), on the "Filenames and Paths" screen. Hilight the "Extnl Editor" item, then press [Enter] and enter the command you'd normally use to start your editor from the *DOS command prompt* there, and save your setup. Icom will then call your external editor when you select "Create" or "Edit" from within the Script Manager or when a script error occurs. If you defined an external editor previously and wish to reverse your decision for now and use the internal editor, do the same as outlined above but CLEAR the "Extnl Editor" item in the main setup (hold down the [Del] key until the item is clear, or press [Ctrl-End] once to clear the item while editing it), then re-save your setup. Icom will then use its internal text editor. 1.7 Stopping Scripts Before we create and run a script, it'll be useful for you to first know Intellicomm v2.01 SCRTUTOR.DOC 5 how to STOP one, if something goes wrong. To stop a script, just press [Alt-Q] (Q for Quit), relax (the script is paused while you're in the [Alt-Q] menu or any other menu) then select "Abort Script Only" to cancel the script without cancelling the entire job (if the script was called during an automated job... more on that later), or select "Abort Job/Script" to cancel both the script and the job. To activate script debugging, which runs a script one line at a time, showing you each line before it is executed select "Script DEBUG" from the [Alt-Q] menu. Script debug can also be helpful in learning script writing, since it slows script execution down, allowing you to study each command before it is executed, and see its result after it is executed. If you forget the [Alt-Q] command, just press [Alt-Z] to pop up the Terminal menu (the terminal is where all scripts are executed from, regardless of where they're started from) and select "Job and Script Control Menu" from the menu, which has the same effect as pressing [Alt- Q] from the Terminal. [Alt-Z] can be your panic button if you forget the [Alt-Q] key. 1.8 Creating and Running Your First Script Most computer language tutorials begin by showing the student how to print the message "Hello, World" to the screen. It's a quick way to actually accomplish something, so we'll start by doing this here as well. To begin, start Icom if necessary, then access the Script Manager by pressing [Alt-U]. If [Alt-U] doesn't work, then you're in an area of Icom where the hotkeys are disabled, and you'll have to exit that area back to any 'major' Icom area, then try again. Note that these "follow along while reading" bits are very quick, so if you're considering printing this document now, don't (unless you don't mind doing so). For 99% of the tutorial you will simply read along in the online help or File Viewer, (without wasting paper) without 'doing' anything but learning. Just grab a piece of paper and write the few short script lines down before exiting this document and entering the Script Manager. Writing the commands down also helps the brain to remember things better. From the Script Manager select "Create" to enter the editor (whether internal or external) to create a new script. Once in the editor type the two lines below, pressing the [Enter] key after each line. If you make a mistake, use the backspace key (just above the [Enter] key) to correct it. Case is not significant when entering script commands; 'PRINT', 'Print', and 'print' all do the same thing. Use whichever you prefer: print "Hello, World!" pause Once you have these two lines entered, save the file as HELLO.SCR and exit the editor (from Icom's internal editor, just press the [Esc] key to exit, answer "Yes" when asked if you want to save your work, then enter HELLO.SCR when asked for a filename. You're on your own if you're using an external editor. See your editor's help screens if you don't know how Intellicomm v2.01 SCRTUTOR.DOC 6 to save and exit.) If you're asked whether to overwrite an existing file, someone probably gave you a copy of Intellicomm that had already been "used" (they already read this and created their own HELLO.SCR). If that's the case just overwrite the existing file when asked. Once you return to the Script Manager you should see HELLO.SCR displayed in the list of script filenames. To execute the script, move the top hilight bar to HELLO.SCR with the [Up] / [Down] cursor keys (or move the mouse cursor to HELLO.SCR and click), then select "Run" from the bottom menu by pressing the [R] key, or by moving the mouse cursor to "Run" and clicking. Intellicomm should then switch to the Terminal screen, print the message Hello, World! to the screen, and pause for a keystroke. When you press a key the script will end and you will be returned to the Script Manager. Did it work? If so, congratulations! If not, please start over, and check your typing carefully. You may have missed a " quote or left a space out accidentally. 1.9 A More Exciting Example It's nice to be able to print the message "Hello, World" to the screen, but it certainly isn't very impressive or exciting. Let's try something a little more interesting this time. You know what 'menus' are if you've been using Icom for any length of time, and now it's time to demonstrate how easy it is to create a menu using an Icom script. You may even impress your friends or co-workers with this next script! Select "Create" again from the Script Manager to enter the editor and create a new script, then type in these three lines exactly, double- checking all the quotes, spaces and tildes (~): MENUDEFINE "Option ~1" "Option ~2" "-" "Option ~3" "Option ~4" MENUBOXV "My Own Menu" "Your selection, Sir?" PAUSE "You selected Option " $MENUSELECTION When done, save the script to disk but this time as MENU.SCR (from the internal editor, press [Esc], answer "Yes" to save it, then enter MENU.SCR when asked for a filename; again overwrite if a MENU.SCR already exists). When you return to the Script Manager, hilight MENU.SCR and select "Run" to see what you've created. If you entered the lines above exactly, you'll have created a centered box menu, with title, four menu options with a divider line separating items 2 and 3, hotkeys, and mouse support! Of course, the menu doesn't actually 'do' anything yet other than print which option you selected (or 0 if you press the [Esc] key)... you'd have to add a few more lines to the script to get the options to do something. However, just being able to display such a menu on the screen with working hilight bars and mouse support (and even a screen blanker, if Intellicomm v2.01 SCRTUTOR.DOC 7 that feature is turned on in the Icom main setup) is no small programming task. Yet you accomplished it in about 30 seconds! We used "Option ~1" and so forth above, but the options can be any text you like; as long all the options remain on the same line, each in double quotes, separated from one another by a space. The "~" character tells MENUDEFINE where the 'hotkey' is. Using a single hypen "-" as a menu option specifies a divider line. $MENUSELECTION is a 'System Variable' which Icom sets after menu-handling commands to tell you which (if any) item was selected from the menu. There are about a hundred of these System Variables available (all starting with $) and each is documented fully in SCRIPT.DOC. By testing the $MENUSELECTION variable with an IF or SWITCH command, you could have various other commands carried out according to the menu option the user selected. Example (text after a semicolon ; is ignored by the script processor and is used to make comments for human consumption): ;The first IF means "IF $MENUSELECTION is equal to 1" If it is, then ; the command following the IF is executed. If not, the command is ; skipped. IF $MENUSELECTION = 1 print "Downloading file..." ;these commands are only download "Z" "" ; executed IF $MENUSELECTION ...etc. ; is equal to 1 ENDIF IF $MENUSELECTION = 2 gosub Item1Selected ;go to a subroutine A better way to test the value of $MENUSELECTION though is to use the SWITCH command. SWITCH is designed specifically to test a variable such as $MENUSELECTION for multiple conditions, and to carry out one command (or set of commands) according to the value of the variable. Read the comments (after ;) for an explanation: SWITCH $MENUSELECTION ;specify the variable to test case 1 ;is $MENUSELECTION equal to 1? print "Option 1 selected" ; yes, print this ... ; execute as many commands as you like endcase ;'end of case 1' (the rest are skipped) case 2 ;is $MENUSELECTION equal to 2? print "Option 2 selected" ; yes, print this ... ; and execute whatever commands you like endcase ;'end of case 2' (the rest are skipped) ... ;and so on with as many 'case/endcase' as ; needed default ;default is an optional 'case' that is ... ; carried out if no other cases are true endcase ;end of 'default' case ENDSWITCH ;mandatory 'end of switch' statement If $MENUSELECTION was equal to 1 (i.e. if the user had selected option 1 from the menu) then ONLY the command(s) between "case 1" and its Intellicomm v2.01 SCRTUTOR.DOC 8 "endcase" would be executed. Note that "case 1" isn't fixed text. You won't always use "case 1", "case 2", etc. In some cases you might use this: case ".ZIP" ;is the SWITCH equal to ".ZIP"? endcase case 12345 ;is the SWITCH equal to 12345? endcase ...etc. Only the word "case" is fixed. Whatever follows the word "case" is compared to the variable specified in the SWITCH ($MENUSELECTION in this example) and if they're equal then the commands between that case/endcase are carried out. If they aren't equal, the case (to its ENDCASE) is skipped, and the next 'case' is checked. When you're ready for more information on using menus, see the MENUDEFINE, MENUBAR, MENUBOXH, MENUBOXV, IF and SWITCH in the DETAILED COMMAND SUMMARY section of SCRIPT.DOC. Also see SCRDEMO.SCR and POSTFILE.SCR for practical examples of menu and SWITCH usage. 1.10 Other Ways of Running Scripts The scripts you just wrote, as with any Icom script, can be executed in all sorts of different ways. You can run them from BIFs, from Jobs, from the DOS command line (using a .BAT file or menu system, for example), from another script, or from the Script Manager. 1.10.1 Running Script from BIFs Scripts can be executed from a BIF by simply specifying @SCRIPTNAME as the response to a prompt: | Your Logon Name> @HELLO Name . . . . . . st Name? Æ | ^^^^^^ Another useful way to run a script from a BIF is via the "Connect Command" item on BIF screen 1. This command (or @SCRIPTNAME) is executed as soon as Icom connects to the BBS, before it gets any logon prompts. 1.10.2 Running Scripts from Jobs Scripts can also be executed by a job "Custom Command" (defined in the Icom Job Editor, where you define all your automated jobs) again by specifying @SCRIPTNAME as the Custom Command: | 12 Custom Command/Run script | CC: @MENU | ^^^^^ The above two methods of running scripts allow you to run any script just about ANYWHERE during an automated job. Note that the .SCR extension is not specified in the examples above. You 'can' specify the extension if you like, but Icom supplies the .SCR extension if no extension is given, so it's just extra typing to add it (though it can add clarity to specify a .SCR extension). BIFs and Custom Commands are the only two places where you must specify '@' before the script name, and the reason for that is to tell Icom to run a script instead of doing what it usually Intellicomm v2.01 SCRTUTOR.DOC 9 does: send the text you define to the BBS. 1.10.3 Running Scripts from DOS Another way to run scripts is via the /scr: command line switch. Example: ICOM.EXE /scr:MENU This example above would cause Icom to switch to Terminal mode, run your MENU.SCR which we just created, display the menu (and handle any options in it, if there were real commands hooked up to the menu), then exit back to DOS as with the /run: command line switch, which does much the same thing, but for automated jobs instead of scripts. 1.10.4 Running Scripts from Scripts You can also execute a script FROM a script using the SCRIPT command. Example: SCRIPT "MENU" ;run MENU.SCR from another script print "Hello, World!" pause If you ran the above script, MENU.SCR would be executed (until completion... it could handle all sorts of different tasks) and when MENU.SCR finished, the message "Hello, World." would be displayed. (The Hello, World is simply used to show you that the original script continues execution after MENU.SCR finishes.) Again, you can add the .SCR extension if you like, but it's not necessary. Calling one script from another is not something many people will have to do, but the ability is there if needed. Note that no @ is required in either of the above examples when specifying the script name. You can also run scripts from scripts by calling up the Script Manager and allowing the user to hilight/Run one or more scripts, using the SCRIPT command but WITHOUT specifying a script filename after the command: pause "We interrupt this script to bring you the Script Manager..." SCRIPT ;the user could Tag/Run one or more scripts ; ...this script would continue below when all ; the other scripts were finished print "We now continue with our regularly scheduled program..." Note above that instead of using PRINT to print a message, and then PAUSE to wait for a keystroke, both were combined into a single PAUSE command. PAUSE accepts an optional message to PRINT before pausing. 1.10.5 Running Scripts from the Script Manager Of course, scripts can also be executed from the Script Manager by Intellicomm v2.01 SCRTUTOR.DOC 10 pressing [Alt-U] in Icom to access the Script Manager as you've just done (the Script Manager can also be used when online, by simply pressing [Alt-U] in Terminal mode... Again, it's on the [Alt-Z] terminal menu if you forget the key). You can also Tag and Run scripts one after another from the Script Manager, similar to what you can do with jobs from the Job Directory -- though this is useful only if the scripts you Tag/Run are DESIGNED to run one after the other. Further, Tagged scripts are executed in the ORDER IN WHICH THEY ARE DISPLAYED in the Script Manager, but you can easily change this order by renaming scripts (using symbols or numbers, like 1SCRIPT.SCR, 2SCRIPT.SCR, or !SCRIPT.SCR to sort to the top, etc). 1.10.6 Running Scripts via Function Keys And if the above isn't enough variety you can also "attach" scripts to function keys so a script executes when you press a key. This is best accomplished using Script Learn which asks you whether to attach the script to a function key or not. To attach a script to a key manually you must look in the Appendix of the SCRIPT.DOC manual (or in the online script help) for the "Key Code" of the function key, and must name the script using the numeric key code for the function key to attach to. Zeros must also be padded on the left side of the script name to make it exactly eight characters long. For example if you looked up the Key Code for the [F2] key you'd see that was 15360. To attach a script to the [F2] key then, you would name your script 00015360.SCR. From that point on, whenever you pressed the [F2] key from Terminal mode, 00015360.SCR would be executed. The leading zeroes MUST be added or the script will not execute when you press the key (this avoids conflicts with other scripts that just happen to use a number as the filename). Further you must use a function key (the key alone, or in combination with [Alt], [Ctrl] or [Shift] ... they all have unique Key Codes) and cannot use the [F1] key or any other keys. [F1] is reserved for online help and for future expansion. 1.11 It Can't be That Simple, Can It? Writing and using scripts can be as complicated or easy as you want it to be. There are many EXTREMELY easy-to-use script commands available to put loads of power into your hands with very little effort. To prove this point further, let's assume that you want to dial a BBS, make sure you're connected, perform a complete logon responding to every question asked by the BBS, keep an eye out for the BBS main menu so you'll know when the logon is complete, AND implement some sort of error handling so that if something goes wrong and you don't reach the main menu after, say, two minutes, you can give it up and hangup. To make it interesting, you also want to hangup if a BBS event is scheduled, and if you DO logon successfully, you want to capture BBS bulletin #5 to a file called BLT5.TXT, then logoff and hangup. If someone asked you to write a script to do this, what would you tell them? You'd probably tell them to get bent (or to use Intellicomm's built-in automation routines, which would make a lot more sense), but Intellicomm v2.01 SCRTUTOR.DOC 11 you'll be able to do this on most any BBS just a few minutes from now. It may seem a rather meaty assignment to be jumping to after "Hello, World", and with some script languages you'd be in for a rather complicated bit of script writing and concept learning to get the job done. With Intellicomm you get most of the work done with three commands: WHEN, SEND and WAITFOR. Here's the example (explanation follows the example): dial "Joe's BBS" 1 ;place the call offline goto ExitScript ;jump to label ExitScript: if not connected when "Enter Language #" send "1" when "graphics (Enter)=no?" send "N" when "st name?" send "John Smith" when "Password" send "Mypassword" when "Scan Message Base" send "N" when "More?" send "N" when "(Enter) to" send "" when "upcoming EVENT" goto HangItUp waitfor "Command? " 120 HangItUp ;the logon is now complete when ;clear all the whens, no longer needed cappush ;save capture filename/state (open/closed) capture "BLT5.TXT" ;open a new capture file send "B 5 NS" ;get bulletin 5, non-stop mode (PCBoard) waitfor "Command? " 120 HangItUp cappop ;restore the old capture file send "G" ;send [G]oodbye to logoff HangItUp: ; <-- here is where 'HangItUp' is hangup ;hangup the modem ExitScript: ; <-- here is where 'ExitScript' is exit ;end the script Just twenty lines gets the whole job done... and for demonstration purposes the above script is actually more involved than it need be. Ignore the technical details for now (you may still be wondering why there are double quotes around some items, etc.) and just take it one step at a time. The DIAL command (the first command in the script) is used to dial a BBS. The text following the dial command tells Icom which BBS to dial: in this example Icom would search your BBS Directory for a BIF with a description of "Joe's BBS", and if found it would Tag the BIF and "Dial" it. Note the '1' following "Joe's BBS". This tells DIAL that the BIF description must match exactly, and the '1' is optional. If the 1 is omitted, then any portion of any BIF description that had the text "Joe's BBS" in it ("Joe's BBS 2", etc) would also be tagged. Thus, you can also Tag/Dial multiple BIFs, depending on the descriptions you use to save your BIFs. If you had ten BIFs that had exclamation marks in their descriptions (Joe's BBS!, CRS!, Sound Advice!, etc), then you could just specify the exclamation mark, and omit the '1' following Intellicomm v2.01 SCRTUTOR.DOC 12 the description (i.e. do not force an exact match): dial "!" DIAL would then Tag/Dial all ten BIFs. When the BBS is connected to, it is untagged automatically. REDIAL can then be used to dial the tagged BBS's you haven't connected to, until all BIFs are untagged. The easiest way to find the proper text to use after the DIAL command ("Joe's BBS" above), if you intend to tag several BBS's by omitting the '1' in the DIAL command, is to enter Icom, press [Alt-D] to switch to the BBS Directory and select "Find" from the BBS Directory menu. Then enter the text you intend to use after the DIAL command ("Joe's BBS", without the quotes), select "Find all/Tag all", and Icom will show you which BIFs would be tagged if you used that text after a DIAL command. That's exactly what DIAL does: it changes to the BBS Directory, then does a "Find all/Tag all" on the text you followed the DIAL command with, then selects "Dial" from the BBS Directory menu. By using certain keywords (or exclamation points, etc.) in your BIF descriptions you can use this to your advantage to dial multiple BBS's with a single DIAL command. On to the next line: 'offline goto ExitScript'. Scripts execute from top to bottom (first line to last) unless told otherwise by specific commands: GOTO is one of those commands, and there are several others. The OFFLINE command checks the modem to see whether it's online or offline (connected or not connected). If the modem ISN'T offline (if we got connected), then Icom ignores the GOTO command and simply continues with the next line of the script. If the modem IS offline (we didn't get connected), then Icom executes the command following the offline command: GOTO in this case. I.e. an 'if' is implied before the OFFLINE command, and you can think of it as "if OFFLINE do this". GOTO causes Icom to goto (jump to) what is called a script 'label'. The label we're telling Icom to goto is label ExitScript:, which gets us down to the end of the script rather quickly (EXIT ends a script immediately). The only time you follow a label with a colon (:) is when you're actually showing Icom WHERE THE LABEL IS. I.e. where to GOTO. You don't follow labels with a colon anywhere else. I said GOTO causes Icom to jump TO the label, but that's not quite true: it jumps to the next line following the label. The label itself can't be executed, so that line is skipped and the script starts executing the line just following the label. If labels are found in the normal running of a script (we didn't GOTO the label; we just happened to run into it) the label is ignored, but any commands BELOW the label are still executed. If that's not what you want, then you simply put a GOTO above the label to to jump around the commands. For example, if the script above wasn't designed to logoff the BBS (we didn't want to hangup), we'd have to jump around the HANGUP command with a 'GOTO ExitScript' just above the label 'HangItUp:'. We could have just used 'GOTO HangItUp' in the OFFLINE command and eliminated the 'ExitScript:' label (the only place the 'ExitScript' label is used is by the OFFLINE command). But there'd be no need to hangup the modem if we were offline, so we put one label above the hangup, and can Intellicomm v2.01 SCRTUTOR.DOC 13 GOTO there to hangup and THEN exit the script, and one below the HANGUP so we can GOTO there and exit the script without hanging up. Using labels and GOTO's, etc., is how you perform decision-making in your scripts, causing some commands to execute under some conditions, and other commands (or no commands) to execute under other conditions. We also could have just used OFFLINE EXIT (if offline, exit the script... which is simpler than jumping to the label below), but two labels and a GOTO were used for demonstration purposes. The next command we run across after 'offline goto ExitScript' is the WHEN command. WHEN uses this format: WHEN "you find this text" do this ('you' referring to Icom, and 'find' meaning if the text comes in the COM port, from the BBS.) WHEN doesn't actually do anything on its own, unless you specify it all by itself, with no parameters following it, in which case it CLEARS all the WHENs defined previously. It's not until WAITFOR is executed that the WHENs become active: WHEN and WAITFOR works as a team. WHEN simply causes Icom to store the text and position of the command following the WHEN in memory, for later use with WAITFOR. WAITFOR activates all the WHENs (all prompts are then watched for simultaneously... you can use up to 19 WHENs at a time) while WAITingFOR specific text from the BBS. Waitfor uses this format: WAITFOR "wait for this text" <how long> <label to GOTO if not found> If the text "wait for this text" is found, the WAITFOR command ends and the script continues with any lines following the waitfor (above we SEND a command to get bulletin 5, open a new CAPTURE file, wait for the menu again, then reset the previous capture file and logoff). The 120 in the WAITFOR command in the script above tells WAITFOR how long to wait before giving up (in seconds; 120 is two minutes) and 'HangItUp' tells waitfor where to jump to (GOTO) if the text ISN'T found within the two minutes. 'HangItUp:', defined just below, skips the capture and executes the HANGUP command to hang up the modem, then it runs into the EXIT which ends the script. WAITFOR can also be used on its own, without WHENs, if you don't need any BBS prompts handled while waiting. If/when any of the text following any of the WHEN commands comes in from the BBS while a WAITFOR is active, Icom executes the command specified by that WHEN (and ONLY that command; none of the commands in the other WHENs are executed until the text they specify is found). If the command specified in the WHEN doesn't turn control over to another part of the script (SEND just sends some text; GOTO turns control over to another part of the script), then Icom just executes the command and continues waiting for the text specified in the WAITFOR. If/when the text specified by another WHEN is found, the same thing happens, and control returns to WAITFOR until the timeout is reached. I.e. the WHENs are just a temporary diversion while WAITingFOR the main objective: the main menu. The WAITFOR timer is not reset after executing the WHEN commands. Two minutes in total, no matter how many times we execute WHEN commands, is how long WAITFOR will wait. I say "wait" because no other commands (other than the WHENs) in the script can execute until the WAITFOR either Intellicomm v2.01 SCRTUTOR.DOC 14 finds the text or times out. I.e. WAITFOR pauses script execution, and the lines below a WAITFOR cannot execute until either the text is found, or WAITFOR times out. The commands used in WHEN statements are just regular Icom script commands, and you can use any script command (or even a set of commands if you use SWITCH, or IF/ENDIF, etc) with a WHEN. The SEND command, used in most of the WHENs above, sends responses to the BBS (no different than you typing the response at the keyboard). Send can also be used on its own to simply send a few commands to the BBS. Send automatically adds a carriage return (same as pressing the ENTER key) after the text, so you needn't worry about adding one yourself: send "J 2" ;PCBoard, join conference 2 send "D" ;PCBoard [D]ownload command send "ICOM201A.ZIP" ;filename to download download "Z" ;download the file using Zmodem The example above probably doesn't even need an explanation other than the "Z" following the DOWNLOAD command. When downloading (or uploading... UPLOAD is the command in that case), to select a protocol, you specify the same letter that you'd press to select the protocol from Icom's protocol menu. If you pressed [PgDn] in terminal mode, you'd see that "Z" is the hotkey used on the protocol menu to select Zmodem. So "Z" is what you specify after the DOWNLOAD command in your script to use the Zmodem protocol. You can use other protocols (including any external protocols you have set up) in the same way; simply by specifying the protocol menu hotkey after the DOWNLOAD command. You could also do this with a WHEN: WHEN "Start your download" DOWNLOAD "Z" If/when the text "Start your download" came in from the BBS during a WAITFOR, Icom would begin a Zmodem download. Zmodem doesn't require the name of the file to download since the protocol itself (Zmodem at the BBS) passes the filename. The above DOWNLOAD command could even perform a 'batch' Zmodem download, since all the logic to perform multiple-file downloads is built into the protocol. No filenames need ever be specified when downloading with Ymodem OR Zmodem; the filename(s) are specified by the sender. Xmodem and its cousins Xmodem-1K and Xmodem-1k-G do require a filename, since the Xmodem protocol wasn't designed to pass filenames. Further, since Xmodem doesn't pass the filename it cannot perform multiple-file (batch) downloads. If using an EXTERNAL protocol it's up to you to know whether the protocol requires a filename on downloads (if it does require a filename, the name is specified immediately following the protocol letter; Icom will pass the filename to the protocol). *ALL* protocols require filenames for uploads: UPLOAD "Z" "ICOM201A.ZIP" "ICOM201B.ZIP" UPLOAD "Y" "*.ZIP" "D:\TEMP\A???.*" Intellicomm v2.01 SCRTUTOR.DOC 15 The first command would upload ICOM201A.ZIP and ICOM201B.ZIP, using Zmodem. The second would upload any files with a ZIP extension (anywhere on the Icom 'Upload PATH' defined in the main setup or current BIF), and any file in the D:\TEMP directory with an 'A' followed by any 3 characters, and any extension. [Regular DOS wildcards... check your DOS manual if you aren't familiar with wildcards.] Again, you can only specify multiple filenames with Ymodem (or Ymodem-G) and Zmodem, or an external protocol that supports 'batch' uploads. Xmodem does not support batch uploads or downloads. You can also create a 'list' of filenames using the Text Editor, then have the protocol use the list to get the filenames to upload: UPLOAD "Z" "@FILES.TXT" Zmodem would read FILES.TXT, and upload all filespecs on the list. Each filespec may contain a drive/path, and may use wildcards. When using text lists, you specify each filespec on a separate line of the file: C:\TEMP\SOMEFILE.ZIP A???.* *.ZIP Note that these rules also apply when uploading manually... you can do all of the above (minus the quotes) when specifying filenames at the Upload filename prompt. 1.12 Variable Overview Variables are a very useful script feature, and can increase the usefulness and flexibility of your scripts significantly. They're not something you 'have' to know about to write scripts, but are something you probably will WANT to know about, since they're extremely useful. Variables are nothing more than "places to put things". Some variables come with 'things' already in them (information which you can use in your scripts), while other variables are created by you (via the VARIABLE command) to allow you to keep track of your own 'things'. If you wish to count something, such as the number of times a certain error happened, a variable is needed. If you wish to know what time it is, you use another variable. There are six different types of variables you can make use of in your scripts, and only a quick overview of variables is given in this section. Detailed information on all six types of variables, plus many examples of usage, can be found in section 4 below. System Variables ~~~~~~~~~~~~~~~~ All System Variables begin with a dollar sign ($). They are used to access all sorts of information about your computer system, and the current status of Intellicomm itself. They also make your scripts much more flexible, since they allow you to avoid specifying constant data. Examples: Intellicomm v2.01 SCRTUTOR.DOC 16 SEND $PASSWORD ;send the BIF logon password PRINT $DATE ;prints the current date IF $DOW = 1 PRINT "Today is Sunday" ;$DOW is the Day-Of-Week IF $DOW = 2 PRINT "Today is Monday" ; ...etc. The first IF means 'if the day-of-week ($DOW) is equal to 1 (Sunday)', then PRINT "Today is Sunday". If $DOW is NOT 1, the PRINT following the IF is ignored. There are a hundred or so different System Variables available and all are outlined quickly in the SCRIPT COMMANDS AT A GLANCE section, and (in more detail) in an appendix at the end of the SCRIPT.DOC manual. Anyone and everyone can and should use System Variables... they're very straightforward and useful. As with all the other types of variables listed below, you can use a System Variable in ANY script command that takes a parameter, instead of using constant text or a constant number. User-Defined Variables ~~~~~~~~~~~~~~~~~~~~~~ These are variables you define yourself using the VARIABLE command. If you wish to count something, you might define a variable called 'count': VARIABLE count ;this command defines variable 'count' and ; assigns 0 to it (0 is the default) VARIABLE ten 10 ;this command defines variable 'ten' and ; assigns 10 to it. INC count ;INCrement count (count = count + 1) ADD count ten 5 ;count = 10 + 5 If you wish to store your name, you might use this: VARIABLE LogonName "John Smith" Later in your script, instead of using SEND "John Smith", you could use SEND LogonName. These variables also allow you to avoid 'hardcoding' information into your scripts, and thus they allow a single script to serve more than one purpose. Instead of DIAL "Joe's BBS", you can get user input from the keyboard, store the input in a variable, then use the exact same script to dial multiple BBS's. Further, these variables also make your scripts easier to maintain. If you define all your variables in one section of the script, and later something changes (a BBS prompt, for example), you can simply change the value assigned to the variable without having to change dozens of WHEN commands. "Variables" are also what enables Intellicomm to automate calls to different BBS types. It simply loads the BIF information into its variables... and the program then behaves differently, since it's using different data. Many script commands also REQUIRE a variable as the first parameter, in order to store the results of an operation. For example the ADD command adds two numbers and stores the result in a User-Defined Variable. The GETS command gets input from the keyboard, and also stores the input in Intellicomm v2.01 SCRTUTOR.DOC 17 any User-Defined Variable: VARIABLE myvariable ;define a variable called 'myvariable' GETS myvariable 60 ;get (max) 60 characters from the keyboard, store ; the input in 'myvariable' PRINT myvariable ;print the result User-Defined Variables exist only from the time of their creation with the VARIABLE command until the current script ends. They are also 'local' to the current script, so if you execute another script FROM a script with the SCRIPT command you needn't worry about changing the contents of the variables in the first script. The Global Variable Array (GlobalStr) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a variation of the User-Defined Variables. But the 'Global' Variables exist in memory for the duration of the Icom session. Unlike the User-Defined Variables, these variables are 'globally' available to all scripts, and still hold their values after the script ends (used mainly for inter-script communication and the like). They also employ a concept known as an 'array'. The GlobalStr array is where script command line parameters are stored, if you pass parameters to a script from a BIF command, or job Custom Command, or from the DOS command line. Use of the GlobalStr array is more advanced than most other script concepts and will probably only be needed by advanced script writers. BIF Variables ~~~~~~~~~~~~~ These variables allow you to access any information from the BIF currently in use (the BBS you're currently connected to, or the BIF you explicitly load with the LOADBIF command). BIF variables are also somewhat advanced and probably won't be needed immediately. See the BIF VARIABLES section in SCRIPT.DOC when you're ready for more information. Main Setup Variables ~~~~~~~~~~~~~~~~~~~~ These variables allow you access any information from the INI (INItialization file) currently in use; normally ICOM.INI (you can also load Main Setup files with the LOADINI command). The Main Setup Variables contain all the main data you define in the Intellicomm Setup. Again, these variables are somewhat advanced and you can leave them for the time being. When you're ready for more information, see the MAIN SETUP VARIABLES section in SCRIPT.DOC. Permanent Variables ~~~~~~~~~~~~~~~~~~~ Permanent Variables make use of the script "File Input/Output" commands to store information on-disk. The concepts aren't overly difficult to grasp, but again won't be needed by everyone. See the INTRODUCTION TO FILE INPUT / OUTPUT, here in SCRTUTOR.DOC, when you're ready for more information. Intellicomm v2.01 SCRTUTOR.DOC 18 1.13 A Word on Formatting You may have noticed above in some of the example scripts that certain items 'lined up' with each other (the SEND commands after the WHENs, for example), and that the comments are in a certain position, etc. But this is done only to please the eye, and the only rules that are forced on you as far as formatting goes are these: 1. Every script command (including any parameters that follow the command) must be on a separate line. EXCEPTION: If the script command is designed to take another command as one of its parameters (such as the OFFLINE and WHEN commands demonstrated above), then you may (and must) place more than one command on a single line. Just don't try to do this: dial "Joe's BBS" offline exit ;both on the same line If a command accepts another command as a parameter, the Detailed Summary of the command will tell you so. If a command isn't expected as a parameter, you can't use one. 2. At least one space or TAB character must separate the script command from the parameters (if any), and at least one space/TAB must separate each parameter. Example: COMMAND "parameter 1" "parameter 2" ... These are errors: COMMAND"parameter1" or COMMAND "parm1""parm2". ^ ^ One or more spaces (or a TAB) are needed where the carets (^) are. 3. Only the first 256 characters of each line are used by the script processor. You may create lines that are longer than 256 characters (comments that go past the 256 character mark, etc.), but only the first 256 characters are significant to the script processor. This will probably only be relevant when using the MENUDEFINE command, which uses the format: MENUDEFINE "Menu Item 1" "Menu Item 2" ... etc. You'll have to make sure to fit all your menu items in the first 256 characters for it to work properly. If you run into problems, use variables instead of literal strings and use short variable names. Example: VARIABLE i1 "Menu Item ~1" VARIABLE i2 "Menu Item ~2" ... ; "..." denotes more of the same MENUDEFINE i1 i2 ... 4. Script 'labels' used to define where a GOTO (and GOSUB) should jump to must on a line by themselves, must be followed by a colon, and there must not be any spaces or tabs anywhere in the label right up to the colon. The only characters you can use in labels are A-Z, a-z, 1-9, and the underscore (_). Labels are not case-significant (LABEL: is the same as label:). NOTE: comments are permitted after labels, but you must put at least one space or TAB between the label and the comment. Example: HangItUp: ;this label HangItUp Intellicomm v2.01 SCRTUTOR.DOC 19 5. Comments must be preceded by a semicolon (;) and may appear on the same line as a script command or label (after the command/label and all parameters), or may be placed on a line by themselves. Comments must also be separated from the command/parameters by at least one space or TAB. These comments are invalid: HangItUp:;This comment isn't separated from the label dial "Joe's BBS";This comment isn't seperated from the parameter. These comments are fine: HangItUp: ;This is fine with a space dial "Joe's BBS" ;This is fine with a space All characters following a semicolon (to the end of the line) are ignored by the script processor. The one exception to this is if the semicolon is inside quotes. 1.14 Why the Double Quotes ""? Double quotes, such as the quotes surrounding the text after the WHEN and SEND commands above are used (a) to keep all the text together as a single unit/parameter, (b) to allow you to use text between the quotes that would otherwise 'mean' something to the script processor (semicolons, for example, which cause Icom to ignore the rest of the line, and spaces or tabs which signify the end of the parameter), and (c) to tell the script processor that it's dealing with literal text instead of a variable. Variable names are never put in double quotes. A quick note: if the text you're putting between the double quotes has one or more double quotes IN it, then you must 'escape' the double quote with a caret. Example: "This text has ^"double quotes^" in it" Quotes are never used to surround script commands or labels. They're only needed in the parameters (if any) following script commands, and only if the parameter is specifying constant TEXT (as opposed to a variable name, or a constant number containing only characters from 0-9). 1.15 Specifying Control Characters To specify a control character in a script command parameter (backspace, carriage return, escape, line feed, form feed, Ctrl-A, Ctrl-B, Ctrl-C, etc., are 'control characters') simply precede the control character with a caret (^). For example, Ctrl-A would be specified as "^A", Ctrl-B is "^B", escape is "^[". Refer to the ASCII table in the appendix of SCRIPT.DOC (or in the online help) for the complete list of control character codes. Here's an example of sending two escape characters to the BBS (SENDNC sends without adding a Carriage Return. The NC means 'N'o 'C'arriage Return): SENDNC "^[^[" ;SENDNC doesn't add a CR as SEND does Intellicomm v2.01 SCRTUTOR.DOC 20 If you have to use a caret (^) for some reason, you must use TWO carets or the script processor will either ignore it (if used alone), or will convert the next character to a control character: PRINT "^^" ;print a single caret To enter the control character ^^ (ASCII code #30), hold down the [Alt] key and type 3 then 0 on the NUMERIC KEYPAD, then release the [Alt] key. 1.16 Tildes You can cause a one second pause between characters with SEND/SENDNC, or SENDNP/SENDNPC by using a tilde (~): SENDNC "^[~^[" ;send ESC, delay for 1 second, send another ESC A delay is almost ALWAYS required by BBS front ends which require you to press ESC twice before logging on. For some reason, they don't seem to accept two rapid ESCapes. Again if you want to send a tilde, escape it with a caret: SENDNC "^~" ;sends a tilde (~) Tildes are only relevant (and need only be escaped with ^) when you use them with SEND/SENDNC or SENDNP/SENDNPC (i.e. when sending data out the COM port). You needn't and shouldn't escape tildes with a caret in any other script commands. TIP: If you're thinking of writing logon scripts to use in your automated jobs just for this purpose of sending ESC characters to bypass a BBS front end, it is not needed. Just specify the ESCapes in the BIF "Connect Command" option on the 1st BIF screen: | Dial Prefix . . Connect Command ^[~^[ | The above Connect Command causes Icom to send an ESC, pause for one second, then send another ESC as soon as it connects to the BBS. This should get you by most all BBS front ends. 1.17 Specifying Numbers When specifying constant numbers in scripts (i.e. in math operations, or when a number is expected as a parameter as with the timeout in WAITFOR) you needn't and shouldn't put quotes around the numbers: GOTOXY 1 1 ;move the screen cursor to the top left corner Why? Well, numbers never use quotes or semicolons or spaces in them as constant 'strings' (text) might, and they never conflict with variable names since you can't specify a number as the first character of a variable name. Further, you must not use symbols or commas in the number, unless the Intellicomm v2.01 SCRTUTOR.DOC 21 parameter is to be used as a 'string' and is in quotes (i.e. if using it in a PRINT or WHEN or other command that takes TEXT as a parameter rather than a number). As soon as the script processor finds a non-numeric character in a parameter -- when it's expecting a NUMBER as a parameter - - it ignores all following characters: ADD result $5.00 $10.00 ;this causes an error, since $ signifies ; a System Variable. Icom would look for ; System Variables called 5.00 and 10.00 ; ...wouldn't find them, and would abort ; the script with an error. ADD result "50.5" 30 ;'result' will be 50 + 30 (the quotes are ; stripped, the "." is not a number and is ; thus ends the 1st number) PRINT "$5.00" ;text is expected by PRINT, and is in quotes, ; so this is fine ADD result 2,000 3,000 ;'result' will be 2 + 3 due to the commas WHEN "2,000" send "3,000" ;text is expected by WHEN and SEND, and is in ; quotes, so this is fine This version of the script language automatically strips quotes from numbers if you use them... so this is 'legal': GOTOXY "1" "1" But the above is not good programming practice and isn't a good habit to get into. Most programming languages consider it an error to put constant numbers in quotes, since numbers are stored differently by computers than text/strings are. You should get into the habit of leaving the quotes off when specifying constant numbers, even though it really makes no difference to this version of the script language. 1.18 Numeric Limits Constant numbers (or numbers stored in variables that you plan to use in place of a constant number) are limited to the range: -2147483648 to 2147483647 That's about two billion negative and positive. The limits may look like they were picked from a hat, but believe it or not those are 'round' numbers to the computer. Computers don't count in decimal (base 10) like we do, so you'll rarely find a number rounded to the nearest 10, 100, etc. The above are the limits of a four "byte" (32 bit) digit. If you go past the limit in either direction (i.e. add, subtract, multiply or divide numbers that end up with a result higher or lower than the limits above), the result will not be valid. 1.19 Compound Statements Compound Statements, while the term might sound scary, are simply groups of script commands on more than one script line, that 'act' similar to a single script line. Three commands allow compound statements, and each of the three has a 'closing' command to signify the end of the compound Intellicomm v2.01 SCRTUTOR.DOC 22 statement: Command Closing Command --------------------------------- IF ENDIF SWITCH ENDSWITCH WHILE ENDWHILE Here's an example: variable x variable y IF x = y print "x is equal to y" pause "Please press a key..." return ENDIF You'll notice above that three commands were placed between the IF and ENDIF. If the comparison turned out to be TRUE (if x was equal to y), then all three commands would be executed. If the comparison turned out to be FALSE (if x was NOT equal to y) then everything between the IF and ENDIF is skipped. You can also "nest" compound statements, or in other words you can place compound statements INSIDE of other compound statements like this: IF x > y ;is x greater than y? IF x = 0 print "x is equal to zero" return ENDIF ;end of the second IF WHILE x > y print x dec x ;DECrement (x = x - 1) ENDWHILE ;end of the WHILE ENDIF ;end of the first IF The first IF above works in exactly the same way as the first example. If x is greater than (>) y then the commands between the first IF/ENDIF pair are evaluated. If x is NOT greater than y, then everything is skipped right down to the last ENDIF. There is no limit as to how many compound statements you can nest, and the second IF above could have another IF, SWITCH or while before its ENDIF, and so forth. It's important to understand that these compound statements ACT as a single script command, for cases such as these: ONLINE SWITCH next_job case 1 gosub do_job_1 endcase case 2 Intellicomm v2.01 SCRTUTOR.DOC 23 gosub do_job_2 endcase ENDSWITCH Above if the modem WAS online, then the SWITCH compound statement (to the ENDSWITCH, executing one or none of the 'cases') would be evaluated. If the modem WASN'T online, then the entire SWITCH (along with any nested compound statements WITHIN the SWITCH/ENDSWITCH) is ignored. This is also legal: ONLINE IF x = y SWITCH ... ;CASE/ENDCASEs here, along with even more ... ; compound statements if need be ENDSWITCH Note that if a command is specified after the IF comparison (after 'x = y' above), then it is assumed that you are using the stand-alone version of IF, instead of using an IF/ENDIF compound statement. Example: IF x = y PRINT "x = y" IF x = y PRINT "x = y" ENDIF Both of the above do the same thing... One uses the stand-alone IF variation (where only one command, or a compound statement is accepted after the comparison) and one uses the IF/ENDIF variation. In the previous example, the SWITCH is legal after the IF comparison since compound statements (and nested compound statements) behave like single script commands. Thus, if the modem was NOT online then everything right to the ENDSWITCH would be skipped. If the modem WAS online then the IF would be evaluated... and again if x was NOT equal to y, then everything to the ENDSWITCH would be skipped. If x WAS equal to y, then the SWITCH would be evaluated. Nested commands (compound or otherwise) progess one step at a time, and whenever something proves to be false, the very next command, be it a single command, a compound statement, or multiple nested compound statements, is skipped. Only after you gain a bit of experience will you want to get into compound statement nesting, but you're bound to run into it sooner or later (and it certainly can be quite useful at times) so it's handy to know how they work. 1.20 Where To Go From Here Congratulations! This ends the introduction. You could quit with this knowledge right now and write some very useful scripts indeed. You know what scripts are, how to write them, how to run them in every way imaginable, how to display information on the screen, including working menus, how to dial a BBS, how to watch for BBS text/send responses, how to perform error handling if key BBS text you're looking for isn't found, how to upload and download files, how to hangup the modem, how to perform Intellicomm v2.01 SCRTUTOR.DOC 24 basic decision-making (GOTO), how to define and use variables, and in general how to use compound and nested compound statements! And you should be able to accomplish just about anything with these skills. There are many more script commands in Icom's script language not demonstrated above that are just as easy to learn and use, just as useful, and will require little explanation to use. If you understood the examples above you'll have no trouble understanding most of the other script commands... It's only a matter of time and hands-on experience until you master scripts completely. And when you master scripts, a whole new world of possibilities will open up to you! Your next step should be to execute the SCRDEMO.SCR (script demo) script if you haven't already, and to then "Edit" SCRDEMO.SCR to see how various tasks were accomplished. When you see a command you're not familiar with, either use the online help "SCRIPT.DOC" link, or the File Viewer (accessable in the Editor via the File|DOS/Open... menu option) to look up the detailed summary of any commands you don't understand, or simply want to read up on. All script commands and System Variables are outlined in the SCRIPT COMMANDS AT A GLANCE section of SCRIPT.DOC, and each command is explained in detail in the DETAILED COMMAND SUMMARY section. EXAMPLES of usage for each command can also be found in the Detailed Summaries. 1.21 The Secret to Success The only real problem you have when writing scripts is in remembering the commands, and remembering what 'parameters' follow the commands (like the "Z" after the DOWNLOAD command). The trick is to ONLY concentrate on the commands you NEED, and to learn (then USE) only one or two commands at a time. Practice makes perfect; take one or two script commands that you need, practice with them and get a script WORKING with them, and only then move on to other commands you may need. You WILL succeed if you take this approach. Most people will use only 5% or 10% of the script commands, and will never bother the other 90% (though 'which' 10% of the script language each user concentrates on varies from person to person, depending on their needs) so don't bother with a command until you need it. Perhaps start with WHEN and SEND, to define your own logon script (note that you MUST define a password in your BIF or Icom will not attempt an auto- logon). Practice calling the logon script from a BIF by placing @SCRIPTNAME in the BIF "Connect Command" item on BIF screen 1: | Dial Prefix . . 1 Connect Command @SCRIPTNAME | SCRIPTNAME.SCR would be executed as soon as Icom makes a connection at that BBS. Try getting the script to answer just one or two logon questions such as your name and password ... get that working, THEN move on to other things. Or you could practice running a script from one of the BIF Logon responses: | Your Logon Name> @SCRIPTNAME Name . . . . . . st Name? Æ | Intellicomm v2.01 SCRTUTOR.DOC 25 SCRIPTNAME.SCR in the example above would start with: SEND "John Smith" since Icom would already have found the "st Name?" prompt ... The script might then continue to define some WHENs to handle other logon prompts: WHEN "dots will echo)?" SEND $PASSWORD ;sends the BIF password WHEN "last read" SEND "N" WAITFOR "Command?" 120 Icom will pick things up wherever your script leaves off (assuming the proper BIF Logon information is defined). You can run a script to answer a SINGLE logon prompt, or you can handle the entire logon (even carrying out a side-job such as capturing the BBS news file, etc.) and leave Icom at the BBS Main Menu. The same applies to mail runs, bank transactions, file transfers, etc. You can execute a script in ANY BIF response slot. As long as the script carries out (at minimum) what the internal BIF command its replacing did (opening a DOOR, etc), you should be fine. Only when you become familiar with these basic concepts and gain experience should you move on to more complex scripts (if you want to learn more... stop whenever you're satisfied with what you've learned). Browse the SCRIPT COMMANDS AT A GLANCE section often in the beginning, just so that you'll at know what commands ARE AVAILABLE for specific tasks. Don't try to memorize any commands... just give it a quick browse so you'll know, in general, what is available. Only when you NEED that task done in a script will you have to bother learning how the command actually works. Imagine the script language as a big plate of assorted appetizers, meant to serve everyone: look the plate over (the SCRIPT COMMANDS AT A GLANCE section), and take what you want. With just a little time and experience, you'll be able to write very powerful scripts that will AMAZE you and give you great satisfaction. Enjoy yourself, and be proud of your accomplishments! Writing scripts that WORK, no matter how insignificant the task, can be a very satisfying way to spend an evening or two. Intellicomm v2.01 SCRTUTOR.DOC 26 2. WHAT HAPPENS WHEN A SCRIPT ENDS? The short answer to what happens when a script ends is, "hopefully the right thing, for whatever circumstances the script left the system in". The longer answers follow: Scripts end when one of four things happen: (1) the end of the script is reached (there are no more commands to execute; this is true even if a subroutine was executed and you forgot to add a RETURN), (2) Icom runs across an EXIT or RETURN or SYSTEM command in a script, which ends the script at that point, (3) the connection is lost and Icom was running an automated job prior to calling the script, (4) the user aborts the script by pressing [Alt-Q] then selecting "Abort Job/Script" or "Abort Script Only" from the control menu. If the user selects "Abort Job/Script" then both the script and the automated job are cancelled. When any of the four events above occur, what Icom will do next depends on whether your modem is connected or not connected (online or offline), where you called the script from, and whether an 'errorcode' was returned by the script in the EXIT or RETURN command. If you run a script from an automated job via a Custom Command, the first thing Icom will do when the script ends is attempt to locate its position on the BBS by sending the BIF "General Menu Exit" command, then watching for a BBS menu (the script may have changed locations, so Icom can't assume it ended up where it was when the script started). If Icom successfully locates its position, the next job task continues (Get Mail, etc., or perhaps even another Custom Command that runs another script). If you call a script from a BIF, by using @SCRIPTNAME in one of the BIF command responses, Icom expects that YOU have made sure that your script did the appropriate thing, and left Icom in the location it needed to be in for whatever it'll be doing next (the same as any command you define in a BIF; you can define anything you want, but if it doesn't do the right thing, your job will probably fail). If you call a script from the Script Manager, after the script stops running Icom checks to see whether you're online or offline, and if online it leaves you in Terminal mode to continue with your BBS session. If the modem is offline when the script ends, Icom returns to the Script Manager (unless you originally entered the Script Manager from Terminal mode using [Alt-U] ... in that case, as with most 'sub-tasks' you execute from Terminal mode, you are returned to the terminal when the script ends). If you run a script from DOS via the /scr: command line switch: ICOM.EXE /scr:MYSCRIPT Icom automatically returns *to DOS* if the modem is OFFLINE when the script ends; but not until processing ALL command line switches. This command is legal: Intellicomm v2.01 SCRTUTOR.DOC 27 ICOM.EXE /scr:MYSCRIPT /run:"Some automated job" Icom would run the script, then the automated job, and THEN if the modem was offline it would return to DOS (note that Icom always saves /Run: switch until ALL other command line parameters are processed. If you put the /run: first, and the /scr: second, the script would still be executed first). If you do something like the above, your script would have to perform the dialing/logon, and would have to either leave Icom connected to the BBS that the job is set up to run on, or would have to HANGUP before exiting so that the job would dial. If Icom is connected when a job is started it assumes you've already connected to the proper BBS and simply begins the job without dialing. If you aren't connected to the proper BBS, the job will probably fail. This is also legal: ICOM.EXE /scr:"SCRIPT1 parm1 parm2" /scr:"SCRIPT2 parm1 parm2" (See section 4.10 for more information on passing parameters to scripts.) If the modem is ONLINE when the script ends (rather, when all command line options are processed) then Icom switches to manual terminal mode. If the modem is OFFLINE, Icom exits back to DOS. If you're designing a script to be called with the /scr: command line option via a .BAT file or menu system (or Windows/DESQview), make sure that you execute the HANGUP command before exiting your script, if you want Icom to exit back to where it was called from (back to DOS, the .BAT file, or menu system). 2.1 EXIT and RETURN Error codes If you use an EXIT or RETURN command in your script, and specify a negative number as the exit code (EXIT -1, EXIT -2, RETURN -1, RETURN -2, etc), then Icom cancels all automated jobs, hangs up, and returns to whatever called it (the Job Directory/Main Menu if an automated job, the Script Manager if called from there, or DOS if called via the /scr: command line option). Using a negative exit code after EXIT or RETURN is a rather potent option that should only be used when the circumstances warrant it. If a positive number follows the EXIT or RETURN command (EXIT 1, EXIT 2, RETURN 1, RETURN 2, etc.) then Icom removes the current BIF from the job queue, hangs up, and won't carry out any further jobs on that BBS (if multiple jobs were Tagged for the current BBS) during the current automated session. Use this one when you run out of time at a BBS, or an EVENT is scheduled, etc., and you don't want to call that BBS back. If zero (0) or no error code is specified after the EXIT or RETURN command (EXIT 0, RETURN 0, or just EXIT or RETURN alone), or the script simply reaches the end without any EXIT/RETURN at all, then it's a regular exit and the the usual rules that govern what happens when a script ends (outlined above) apply. This is what will be used in 99% of the cases to end a script. NOTE: This only applies to the RETURN command when it's used to actually Intellicomm v2.01 SCRTUTOR.DOC 28 exit a script: I.e. if the RETURN is found OUTSIDE of a subroutine (a GOSUB command was not executed previously). If you're simply RETURNing from a subroutine, error codes are ignored. EXIT is used to exit all scripts (if you call a script from a script and want to abort BOTH scripts) while RETURN is used to simply exit the current script back to the caller. 2.2 Using the HANGUP Command for Error-Recovery If your script is called by an automated job (Custom Command or BIF command) and loses track of its position or just can't get out of a tricky situation, the easiest way to recover is to execute a script HANGUP command. This will cause the modem to hangup, and when the connection is lost Icom will abort the script, notice the carrier loss (if during an automated job) and will call the BBS back if any job tasks remain unfinished. Losses of connection are tracked by Icom, and it will only permit *three* losses of connection before removing the BIF from the job queue. If you use the HANGUP command from a script during an automated job, it simply looks like a regular loss of connection to Intellicomm. 3. INTRODUCTION TO SUBROUTINES (GOSUB) Subroutines are indespensible in any programming language. They allow you to carry out complicated tasks with a single script command -- GOSUB, short for "GO" to "SUB"routine. Subroutines are also useful in cutting down on programming/typing errors, since you can write and debug a routine ONCE, then make use of that same bug-free routine in several places in the script. Without subroutines you would be forced to write repetitive sequences of script commands multiple times, thus increasing the chance of making a typing error, or introducing a bug. 3.1 When to use a Subroutine Subroutines should be used to replace repetitive sequences of script commands. For example, if you're doing something like printing a 'Press a key' message, then clearing the screen, you might as well use a subroutine to avoid repeating the exact same commands in multiple places in the script: PressAKey: PAUSE "Press a key... " ;wait for a key press CLS ;clear the screen RETURN ;return from the subroutine Once the subroutine is in place, whenever and wherever you need to pause for a keypress in your script, you just execute the command: GOSUB PressAKey When the script processor runs across a GOSUB command it first saves its current position in the script (the position of the GOSUB command), then it does the equivalent of a GOTO (jumps to the label specified after the Intellicomm v2.01 SCRTUTOR.DOC 29 GOSUB) and begins executing the script at the next line after the label. When a RETURN statement is found, it then restores the position it saved previously, and continues running the script at the next line below the GOSUB command. Subroutines can also be used to make a script easier to follow and thus easier to maintain (add to) and debug. They can also help you to organize your thoughts when you have a complex task to accomplish. Instead of trying to figure out how you're going to fit a complicated set of commands into the EXISTING structure of your script, you can instead write the complicated code elsewhere (concentrating only on one task at a time) in a subroutine, without making a mess of the existing structure of your script. Finally, you can also do the equivalent of inventing new script commands with subroutines. Computer (and script) languages give you "building blocks" in the commands they provide. You won't always find a single command that does exactly what you need, but you can usually get virtually ANY job done by combining two or more commands and placing them in a subroutine. Once the subroutine is written, it becomes basically as easy to use as a built-in script command is. 3.2 Writing a Subroutine Writing a subroutine is no different than writing any other portion of your script, with two exceptions: you must think up a 'name' for a subroutine, and you must use a RETURN command to exit the subroutine (back from where it was called). Example: MySubroutine: print "I am now in 'MySubroutine'" return The above subroutine is called 'MySubroutine' and it could be executed from anywhere in a script using the command: GOSUB MySubroutine ;note that the colon is not specified Subroutines can be placed anywhere in your script, though the most common place to put new subroutines is right at the end of the script. The reason they will normally be placed at the 'end' is so you can easily avoid running into them by placing an EXIT (or RETURN) command just above the beginning of all your subroutines. Example: GOSUB InitScript ;Initialize (define and set up any variables) ... ;main body of script here EXIT ;EXIT (or RETURN) after the main body ;Now you can't run into 'InitScript' accidentally InitScript: ... RETURN ;and you can't run into 'Subroutine2' accidentally Intellicomm v2.01 SCRTUTOR.DOC 30 Subroutine2: ;and so forth... ... RETURN Subroutine3: ... RETURN Remember that the script processor simply ignores 'Labels:' if if happens to run into them in the normal course of running a script. Without the EXIT and RETURNs above, all the subroutines would be executed when the main body of the script ran into the subroutine labels below it. 3.3 GOSUB In Detail When the script processor runs across a GOSUB command, it first saves its current position (the 'current' position will be the END of the line on which the GOSUB was found), then searches from the top of the script for the 'Label' you specify AFTER the GOSUB command. If the label is found, execution of the script then begins on the next script line after the label (labels, which are always followed by a colon, are always ignored). The next time a RETURN is found (whether it was actually in the subroutine or not; you can GOTO out of one subroutine and execute another, then RETURN from there) the position saved when the GOSUB found is then 'popped' off the GOSUB stack, and script execution returns to the next command after the *last* GOSUB (if any). The GOSUB 'stack' (the place where the script processor saves the position of GOSUB commands, before executing the subroutine) can hold 16 positions. Thus, you can execute up to 16 'nested' GOSUB commands (GOSUB from *within* a subroutine) before executing a single RETURN. If you attempt to execute 17 GOSUBs before using a RETURN, you earn a "GOSUB Stack Overflow" error, and your script aborts. As RETURN commands are encountered, the script processor returns to the position of the *last* GOSUB command. Example (see the comments [;] for an explantion): GOSUB Subroutine1 exit Subroutine1: print "Executing subroutine 1." GOSUB Subroutine2 RETURN ;would return to the EXIT below 'GOSUB Subroutine1' above Subroutine2: print "Executing subroutine 2." RETURN ;would return to the RETURN below 'GOSUB Subroutine2' above And again, it makes no difference whether the RETURN commands are actually 'in' the subroutine. If 'GOTO Subroutine2' was used above, instead of GOSUB, the RETURN found in Subroutine2 would cause a return to the EXIT command below the call to Subroutine1. Just picture the Intellicomm v2.01 SCRTUTOR.DOC 31 positions of your GOSUB commands being placed in a hat one after the other (you can't get to the previous position without removing the last one) with the RETURN command simply removing those positions (last in, first out) and you'll have no surprises. Note also that there is no difference between a GOTO label, and a GOSUB label. You can GOTO a subroutine label if you like -- but be cautioned that if a RETURN is found -- and no GOSUB was executed previously (i.e. there are no saved positions on the subroutine stack), it causes the script to end. 3.4 Creating a Subroutine Template If you find yourself writing the same subroutines over and over again in your scripts, you should consider creating one or more subroutine "template" files, which contain your common subroutines. You can call template files anything you like: TEMPLATE.SCR is a good choice. Then, whenever you begin writing a new script, simply hilight TEMPLATE.SCR, select "Copy" from the Script Manager, and copy it to another filename (the name of the script you wish to create). Then begin your script by "Edit"ing the newly copied template. All the subroutines will be in place, and you can begin coding immediately. This practice will also help you to standardize the names of your subroutines, so that you're always using the same subroutine label for a specific function (PressAKey, instead of Press_a_Key, PressKey, etc., which could get confusing after a time). It will also give you more reliable scripts, since you'll be using (hopefully) tested subroutines instead of writing from scratch, where you might make a mistake. Intellicomm v2.01 SCRTUTOR.DOC 32 4. SCRIPT VARIABLES IN DETAIL 4.1 Why Would I Want to Use Variables? Variables are what allow computer programs (and scripts) to "know" something. They give your scripts a memory so that they can remember things, and thus become smarter. If an error occurs, you can have the script remember the error or count the occurrences of errors through the use of variables. If you need the user to enter something (a phone number or the like), you can have your script store what the user enters in a variable, and thus your script can 'remember' what the user entered. Without variables, scripts have no way of remembering anything at all. Variables are also REQUIRED by several of the script commands. If you want to do any math (add, subtract, multiply, divide numbers) get keyboard input from the user, read text files on-disk, or do any sort of string 'handling' (joining two pieces of text together, extracting characters from a line of text, reading text from the video screen, etc.) then you must use variables to store the results. There are six types of variables in the Icom script language: 'User- Defined Variables', which you create yourself in your scripts, 'Global Variables' which are similar to the User-Defined Variables but exist for the duration of the Icom session, 'System Variables', which are similar to the Global Variables, but hold information about your computer system and Intellicomm, BIF Variables, which hold all the current BIF information, Main Setup Variables, which hold all the current INI (INItialization or main setup) information, and Permanent Variables, which are stored on-disk. Each type has a different purpose but the reason for variables of all types is to hold information and thus to avoid specifying CONSTANT data in your script commands. Anywhere you can specify constant data in a script parameter ('PRINT "John Smith"' prints constant data), you can use a variable ('PRINT myvariable' prints the CONTENTS of the variable 'myvariable'). Several examples are given below to show you how to make effective use of all types of variables. 4.2 Where you CAN'T use Variables You cannot use variables in place of script GOTO/GOSUB labels. If you try, you'll get a 'Label not found' error, or worse, Icom will jump to a 'label:' you didn't expect it to jump to. 'GOTO myvariable' (if myvariable was a variable) would cause Icom to look for a LABEL called 'myvariable:'. Thus, you cannot use variable names when a GOTO/GOSUB label is expected. 4.3 User-Defined Variables User-defined variables are variables you create yourself. All you do to create a variable is think up a name for it, then use the VARIABLE command to define it in your script: Intellicomm v2.01 SCRTUTOR.DOC 33 VARIABLE myvariable ;define a variable called 'myvariable' You can also 'assign' something to the variable when you define it by following the variable name with whatever you want to assign to it: VARIABLE myvariable "Please hold this text in myvariable" Once the variable is defined, you can use it in any script command that accepts parameters. If you printed this variable above: PRINT myvariable ...then PRINT would display this on the screen: Please hold this text in myvariable If you intend to upload your script to a BBS for public distribution, User-Defined Variables also make it easier for users of your script to fill in any required information. Instead of forcing the user to weed through the entire script and make prompt or response changes, you can define all the necessary information using variables at the TOP of the script where they can easily be found: VARIABLE YourName "John Smith" ;<-- Put your name here VARIABLE Password "password" ;<-- Put your password here Placing variables at the TOP of the script makes it much easier for a novice to edit, and it also makes it easier for YOU to maintain your own scripts than it would be to have to weed through the script and change WHEN or SEND commands. 4.4 User-Defined Variable Rules User-Defined Variables cannot be used in script commands until you define the variable (give it a name) using the VARIABLE command. And you must define each variable with the VARIABLE command ONCE and only once (per script ... you can use the same variable name in another script). After you've defined it, you can change the contents of the variable using ASSIGN and several other commands, but the VARIABLE command should be used only once per variable. If you do this: variable x 0 ;define variable 'x', store 0 in it variable x 10 ;define variable 'x', store 10 in it Icom will abort the script with a 'Variable exists' error when it finds the second VARIABLE command. What you would do instead of using the variable command twice is this: variable x 0 ;define variable x, store 0 in it ... assign x 10 ;later in the script if you want to change the ; value, you use ASSIGN. This example would store the ; number 10 in variable x. Intellicomm v2.01 SCRTUTOR.DOC 34 ASSIGN can be used to assign either text or numers to a variable. You cannot use a script COMMAND as a variable name: variable waitfor ;duplicates the WAITFOR command If you do this inadvertently, the script will abort with the error: 'variable name duplicates a script COMMAND'. At that point you simply think up a new name (add a 1 to the end of the variable name VARIABLE WAITFOR1 or the like) and you're set. Case is NOT significant in variable names: variable myvariable ;lowercase assign MYVARIABLE 10 ;uppercase... they're both the same to Icom You can store anything in a variable; numbers, text, symbols, graphics characters ... anything you like (including control characters). However, the maximum length for data stored in each user-defined variable is 256 characters. User-defined variable names can also be (almost) any name you like. If you were counting something you might use this: variable count 0 ;define variable 'count', assign 0 to it If you were storing your name, you might use this: variable MyName "John Smith" You CANNOT do this, however: variable My Name "John Smith" ;note the space in 'My Name' Spaces aren't allowed in variable names. You can use only letters, numbers (see below), and underscores (_): variable My_Name 10 "John Smith" ;this is fine with an underscore Further, you cannot BEGIN a variable name with a number: it must start with a non-numeric character. You can use numbers after the first character, but the very first character of a variable name must be either a letter or an underscore. These are all valid variable names: VARIABLE count1 ;numbers are okay after the 1st character VARIABLE c1 VARIABLE _1 but you cannot use this: VARIABLE 1count ;cannot start a variable name with a number Icom stores only the first *30* characters of variable names you define Intellicomm v2.01 SCRTUTOR.DOC 35 with the VARIABLE command in its internal table of variable names, and again only checks the first 30 characters when you specify a variable in a script command parameter. These two variable names are the exact same names to Intellicomm: VARIABLE this_is_very_long_variable_name_1 VARIABLE this_is_very_long_variable_name_2 The cutoff point, 30 characters, leaves Icom with: VARIABLE this_is_very_long_variable_nam for BOTH of the above variable names. The above would abort the script with a 'Variable exists' error, since you can't define the same variable twice in the same script. 4.5 Why All the Rules? The 30 character limit to variable names is common in programming and script languages (some allow more, many allow less) and the main reason is to conserve memory. Every name of every variable you create has to be stored in memory in an internal table, so the script processor can find the data when you specify the variable name in a script command. 30 characters is a reasonable trade-off between memory conservation and functionality. Intellicomm also has to have some way of knowing whether you're specifying a constant number (1 for example is a constant number), or constant text (surrounded by single or double quotes), or a variable. The rules outlined above are how it does it. If a parameter starts with a single or double quote, the script processor knows you're specifying constant text. If a parameter starts with a number it assumes you're specifying a constant number. If a parameter has neither a quote nor 0-9 as the first character, the script processor assumes you're specifying a variable name and will check its internal tables of variable names to locate the proper data. Most computer languages use these same rules to separate constants from variables, and numbers from text (strings). Further, other symbols such as +, -, =, <, >, /, *, %, ^, &, |, $, !, [], (), etc., may all be used for various purposes in future expansions of Icom's script language (or are already used), so for maximum compatibility with future releases you can use only a-z, A-Z, _, and 0-9 (subject to the rule above about numbers) in your variable names. By VARIABLE NAMES this doesn't mean the text you specify between the quotes that is assigned to variables. Between quotes you can use any characters you like (almost... you can't use a real Line Feed or it would put the text on another line... use "^J" [Ctrl-J] for LF). Variable names themselves must never be put in quotes, or Icom will think you're specifying literal text and won't check its table of variable names. If you did this: PRINT "myvariable" Intellicomm v2.01 SCRTUTOR.DOC 36 the text "myvariable" (minus the quotes) would simply be printed to the screen. To print the contents of a variable called myvariable, do not use quotes: PRINT myvariable ;this accesses the CONTENTS of variable 'myvariable' 4.6 Using Variables You can use variables in any of Intellicomm's script commands that accept parameters, instead of specifying the parameters literally. You wouldn't want to have to write five different scripts that all do the same thing, but simply account for slightly different conditions such as a different phone number; so instead of changing one script line then duplicating the entire script, you just use variables, then change the variables, and the script works as is. This command could dial only "Joe's BBS": dial "Joe's BBS" While this script, using variables, could dial any BBS: variable BBSName ;define variable 'BBSName' boxgets BBSName 20 "Dialing a BBS" "Enter the name of a BBS to dial" dial BBSName We used a new command here that you haven't seen before, called BOXGETS and what it would do (given the parameters above) is accept a 20 character string (the 20 following command) in a box that looked like this, but with graphics characters instead of text: +=| Dialing a BBS |==================+ | | | Enter the name of a BBS to dial | | | | > | | | +====================================+ Whatever was entered in the box would be stored in the variable 'BBSName' (the first parameter in the BOXGETS command). You then just DIAL BBSName and whatever name was entered in the box would be dialed. When you check the detailed command summary for BOXGETS you'll find all the details, such as how to check to see whether the user pressed the [Esc] key, how to look for a blank string, etc. You should also look up the DIAL command, since it can be used to simply display the entire BBS Directory, allowing the user to Tag/Dial BBS's... which may be more desirable than what was done above. Intellicomm v2.01 SCRTUTOR.DOC 37 When you apply the same concept we used with the DIAL command above to WHEN, WAITFOR, and all the other script commands, using variables instead of specifying text directly, it allows you to write much more flexible scripts (and you may see more clearly how Icom itself works... it simply loads the BIF information into its variables and executes the same code no matter what BBS is being called). You needn't get variable information from the keyboard; you can get it from a BIF, the Icom main setup data, from a text file on-disk which you can create yourself manually or with other script commands, or you can create variable data on-the-fly based on day of week ($DOW), month ($MONTH), day of month ($DAY), time ($HOUR, $MIN, $SEC), etc. For example: variable BBS_to_call if $DOW = 1 assign BBS_to_call "Joe's BBS" if $DOW = 2 assign BBS_to_call "Canada Remote System" if $DOW = 3 assign BBS_to_call "Sound Advice" ; ...etc. DIAL BBS_to_call The first IF statemtent means 'if the day-of-week is equal to Sunday (1), put the text Joe's BBS in variable BBS_to_call'. If $DOW is equal to 2 (Monday), we ASSIGN another BBS name. I.e. we are ASSIGNing data to the variable on-the-fly, according to the day of the week. You don't have to use variables for the time being, and are actually better off sticking with literal text and numbers until you get the hang of things. In the beginning the main goal is to write scripts that WORK. Writing flexible scripts with variables is something you can look into when you're comfortable with the language and have written a few working scripts without variables. A good way to get practice is to write your scripts with constants first, get them working, and THEN to go and replace one or two of the constants with variables to get the hang of it. 4.7 The Life of a Variable User-Defined Variables have a fleeting life most days. They live (exist in memory) only from the time they are defined with the VARIABLE commmand, and they die (do not exist in memory) when the script ends. Their use is also limited to the current script. If you created one script that did this: variable I_Need_This_Number_Elsewhere 10 ...then created another script and executed that second script using the SCRIPT command and tried this in the SECOND script: print I_Need_This_Number_Elsewhere then Icom would abort the second script with the error: "Undefined Variable; I_Need_This_Number_Elsewhere". Variables defined with the VARIABLE command are accessable only from the script in which they were Intellicomm v2.01 SCRTUTOR.DOC 38 created, and only from the point of creation onwards. You can't do this either: print x ;don't attempt to use here variable x 10 ; when it hasn't been defined yet Before using a variable the FIRST thing you must do is define it with the VARIABLE command. Otherwise Icom won't have the name of the variable in its internal table of variable names, and also won't have allocated any memory space to store the variable data. Variables can be used 'above' the VARIABLE command if you can manage to get the variable defined first. You can do this for example: gosub define_variables ;jumps to 'define_variables:', then returns print x ; <-- to this line when the subroutine 'returns' exit ;exit before we hit 'define_variables' again define_variables: ;beginning of subroutine 'define_variables' variable x 10 ;define variable 'x' for use above return ;end of subroutine 'define_variables' Having variables disappear when a script ends, and only allowing the current script to access them may seem like a limitation at first, but both are actually useful features, and both were done intentionally. If variables DID exist after the script ended, you'd be tieing up memory on the computer, possibly never to be used again during that Icom session. By having variables 'die' when the script ends, all the memory they were using is freed up. The other feature; limiting the use of variables to the current script is also very useful. If you had one script that used a variable called 'x', and you had some important data in 'x' and then called ANOTHER script (using the SCRIPT command, which runs a script from a script) that used the same variable name... you may lose your original value in 'x' if the second script also had an 'x' and modified the value. If variables didn't work this way you'd constantly have to worry about conflicting variable names in other scripts, that might change your original data... and tracking down such problems would not be easy. 4.8 Global Variables For the cases where you DO want certain data to be available from one script to another (for inter-script communication and the like) an 'array' of 'global variables' has been provided. Did your face go pale? I know it sounds rather complicated, but the Global Variables can be very useful and are well worth knowing about. The 'global' script variables are available from the second Icom starts until you exit the program. I.e. they hold their data from one job to the next, from one script to the next (with some exceptions... see below) -- for as long as Icom itself remains in memory. The global variable array is called GlobalStr (Str for 'String'... that means it can hold text OR numbers, as with the User-Defined Variables). Intellicomm v2.01 SCRTUTOR.DOC 39 The term 'array' just means that there are more than one of them: there are 10 in fact. The first is GlobalStr[0], the second is GlobalStr[1], the third is GlobalStr[2], etc., all the way up to GlobalStr[9] (0-9 = 10 variables). The GlobalStr variables are each 64 characters long, so you can't store anything longer than 64 characters in any one of the 10 GlobalStr array members. If you attempt to store something longer than 64 characters, the data will be truncated (cut) at 64 characters by the script processor. Now you're probably wondering about those square brackets, and may be wondering why it's not just GlobalStr1, GlobalStr2, etc. The reason for that, and the reason for arrays in general in all programming languages, is so that you can use ANOTHER variable to specify WHICH of the global variables you want to access. Watch this carefully: variable Name_Data 5 ;define Name_Data, assign 5 to it printnc "Enter your name: " ;print with no carriage return gets GlobalStr[Name_Data] 64 ;get user name, store in GlobalStr[5] print GlobalStr[Name_Data] ;print GlobalStr[5] (The 64 following the GETS command specifys the maximum number of characters to get. Remember; each GlobalStr member can hold a maximum of 64 characters.) Instead of specifying a constant number in the square brackets of GlobalStr, we used the variable 'Name_Data', which was holding the value of 5. So, GlobalStr[5] gets the data, since 5 is what 'Name_Data' was holding. Later in your script you might not remember that you stored the user's name in GlobalStr[5], so it's much easier to just assign the value of 5 to 'Name_Data', and then to use GlobalStr[Name_Data]. It's easier to work with and remember than GlobalStr5 would be, were it not an array. One thing you CANNOT do, at least in this version of the Icom script language is this: GETS GlobalStr[GlobalStr[5]] 64 In real programming languages this sort of thing IS legal... and all it would do is access the contents of GlobalStr[5] to get the array offset. If GlobalStr[5] was holding the value 1, a real programming language would store the result of the GETS command above in GlobalStr[1]. However once we get into things like that, this becomes possible: GlobalStr[GlobalStr[GlobalStr[GlobalStr[2]]]] ...and that's a little too involved to program the script interpreter to handle at present. I may get into it in the future, but didn't have time for v2, so you MUST use either a constant number: GlobalStr[0] to GlobalStr[9] Or a user-defined variable (defined with the VARIABLE command) that is HOLDING a number from 0-9: Intellicomm v2.01 SCRTUTOR.DOC 40 variable globalstr_offset 9 ;assign 9 to globalstr_offset GlobalStr[globalstr_offset] ;GlobalStr[9] You MUST NOT USE SPACES anywhere from GlobalStr[ to the closing ]. These are programming errors: GlobalStr [offset] ;space between GlobalStr and [ GlobalStr[ offset ] ;spaces in the brackets GlobalStr[ 5 ] ;spaces in the brackets It must be kept together as a single unit, with no spaces, and this is the correct way to specify the three example errors above: GlobalStr[offset] GlobalStr[offset] GlobalStr[5] 4.9 Using Global Variables Until you become more familiar with the other script commands and concepts it's difficult to demonstrate any advanced use of these variables. But their purpose is threefold: (1) to allow inter-script communication (access to the same data by multiple scripts... which isn't possible with the User-Defined Variables), (2) to allow 'command line parameters' to be passed to scripts from DOS (the /scr: command line switch) BIFs, Custom Commands, and other scripts (the parameters are stored in the GlobalStr array), and (3) basic array usage, which, in real programming languages is indespensible. The main idea behind an array is to use ANOTHER variable as an index to access members of the array. You can start the index variable ('Name_Data' in the example above was the index variable) at 0, then add one to the index variable whenever you need another global variable: variable gindex 0 ;start at 0 assign GlobalStr[gindex] "Some data" ;goes in GlobalStr[0] inc gindex ;INCrement: gindex = gindex + 1 ; ... later in your script assign GlobalStr[gindex] "More data" ;goes in GlobalStr[1] inc gindex ;gindex now equals 2... ready ; for the NEXT bit of data Or you can use a 'loop' to clear all the variables in the array, or combined with other functions can quickly copy data from various sources into the array. A 'loop' simply means that Icom will execute the commands between WHILE and ENDWHILE (below) as long as the condition specified in the WHILE remains true. I.e. as long as the value in 'offset' is less than or equal to the number 9 (9 being the GlobalStr array limit... GlobalStr[9] is the end of the array). Since we start with 'offset' at 0, and add one to it at the bottom of the loop, the Intellicomm v2.01 SCRTUTOR.DOC 41 commands in the loop will be executed 10 times each. More details on loops can be found in the WHILE Detailed Command Summary. Here's a quick example: variable offset 0 ;define variable 'offset', set to 0 while offset <= 9 ;while offset is less than or equal to 9 printnc "Enter item " ;These five lines in the loop will be printnc offset ; executed UNTIL 'offset' is greater than printnc ": " ; 9. When 'offset' is 10, we exit the gets GlobalStr[offset] 40 ; loop and continue below ENDWHILE inc offset ;increment: offset = offset + 1 endwhile ;end of the 'loop' print "Here is what you entered:" assign offset 0 ;It's very important to reset 'offset' to 0 while offset <= 9 ; or else we wouldn't enter this 'loop' at print GlobalStr[offset] ; all. Remember it's now holding the number inc offset ; *10* due to the loop above, and 10 is NOT endwhile ; less than or equal to nine. Loops and arrays were invented to avoid having to do this: printnc "Enter item 0: " gets GlobalStr[0] 40 printnc "Enter item 1: " gets GlobalStr[1] 40 printnc "Enter item 2: " gets GlobalStr[2] 40 ;this would continue right up to GlobalStr[9] to accomplish ; the same thing the FIRST loop above did. print "Here is what you entered:" print GlobalStr[0] print GlobalStr[1] print GlobalStr[2] ;this would also continue right up to GlobalStr[9] to accomplish ; what the SECOND loop above did. Of course, the same principle can be applied to ANY script command (any commmand that takes a parameter), and GlobalStr isn't limited to GETS and PRINT and ASSIGN. You can use this global array variable anywhere your imagination takes you, with any script command that takes parameters. 4.10 Passing Parameters to Scripts When parameters are passed to a script, either from the BIF: | Your Logon Name> @DEMO parm1 parm2 Name . . . . . . st Name? Æ | ^^^^^^^^^^^^^^^^^ or from a Custom Command: | 12 Custom Command/Run script | CC: @DEMO parm1 parm2 ... | ^^^^^^^^^^^^^^^^^ Intellicomm v2.01 SCRTUTOR.DOC 42 or from a script via the SCRIPT command: SCRIPT "DEMO.SCR" "parm1" "parm2" variable_parm or from the ICOM.EXE /scr: command line option: ICOM.EXE /scr:"DEMO.SCR parm1 parm2" the first parameter is stored in GlobalStr[1], the second in GlobalStr[2], then GlobalStr[3], and so on. The quotes are needed when specifying parameters in the /scr: command line option (see above) to keep it all together. Otherwise DOS separates the parameters due to the spaces between parameters, and they look like separate 'switches' to Icom. Note that when using the SCRIPT command, you can pass VARIABLES instead of literal strings (variable_parm above assumes the script had a variable called variable_parm), which simply has the effect of copying the variable data into the GlobalStr array. As mentioned previously the regular user-defined variables are available ONLY within the script they're defined in. By using variables as parameters in a SCRIPT command, the called script could then access the data by looking in GlobalStr. You can also just copy the data explicitly, if you like, instead of passing parameters: assign GlobalStr[1] "parm 1" ;copy 'parm 1' into GlobalStr[1] assign GlobalStr[2] "parm 2" assign GlobalStr[3] variable_parm SCRIPT "DEMO.SCR" The above has the same effect as the previous example, which specified parameters directly in the SCRIPT command. NOTE: When passing parameters from a BIF or Custom Command, Icom separates the parameters by looking for space " " characters. As soon as a space is found, the data following the space goes in the next GlobalStr member. If you wish to pass a single parameter which CONTAINS a space, you must put the parameter in quotes (similar to DOS command line options): | 12 Custom Command/Run script | CC: @DEMO "parm 1" "parm 2" | ^^^^^^^^^^^^^^^^^^^^^^^ The two parameters specified above would go in GlobalStr[1] and GlobalStr[2] (the quotes are stripped before storing the parameter(s) in GlobalStr). Alternatively you could just put quotes around ALL the parameters (to have them all stored in GlobalStr[1]), then use the STRITEM command to get the individual parameters yourself: | 12 Custom Command/Run script | CC: @DEMO "parm1 parm2" | ^^^^^^^^^^^^^^^^^^^ From inside the script you'd do this to get the individual parameters: Intellicomm v2.01 SCRTUTOR.DOC 43 variable parm1 variable parm2 ;GlobalStr[1] would be holding "parm1 parm2" (no quotes) given the ; Custom Command example above STRITEM parm1 GlobalStr[1] 1 ;get item 1 from GlobalStr[1], put in parm1 STRITEM parm2 GlobalStr[1] 2 ;get item 2 from GlobalStr[1], put in parm2 Please see the Detailed Command Summary for more information on STRITEM. 4.11 Checking the Number of Passed Parameters If you were paying close attention earlier, you might be wondering why the parameters don't start at GlobalStr[0] ... since GlobalStr[0] is the FIRST variable in the array ... not GlobalStr[1]. The reason for that is to allow you to quickly check how many (if any) parameters were passed to your script. The script processor stores the total number of parameters (a number from 0 to 9) passed to your script in GlobalStr[0]. So, if your script REQUIRED 3 parameters to be passed to it, and they weren't all specified, you'd know about it quickly: if GlobalStr[0] <> 3 ;if GlobalStr[0] is not equal to 3 msgwind "Hey, you were supposed to specify 3 parameters!" return endif print "Thanks for the 3 parameters. You specified:" print GlobalStr[1] print GlobalStr[2] print GlobalStr[3] return It's as easy as 0-1-2 (or 1-2-3, whichever you prefer). Of course, this GlobalStr[0] business is something you'll have to keep in mind (a) if you're storing anything important in GlobalStr[0] and (b) if you use the SCRIPT command to call another script from your existing script. I.e. if anything important is stored in GlobalStr[0] (your own data... Icom doesn't care what's in GlobalStr[0]) you'll lose it if you execute a SCRIPT command from within the current script. You can overcome any problems by doing this: variable some_variable assign GlobalStr[0] "Important data" ;holding something important ... ;meanwhile, later in the script... assign some_variable GlobalStr[0] ;save GlobalStr[0] script "ANOTHER.SCR" ;run ANOTHER.SCR assign GlobalStr[0] some_variable ;restore GlobalStr[0] Note that even though you didn't PASS any parameters to ANOTHER.SCR, the script processor would still store the number 0 in GlobalStr[0], to tell ANOTHER.SCR that no parameters were passed. Of course, if you DID pass parameters to ANOTHER.SCR, then GlobalStr[1] and possibly GlobalStr[2], Intellicomm v2.01 SCRTUTOR.DOC 44 etc., would also be lost, depending on how many parameters you specified. If you pass 9 parameters to a script then the entire GlobalStr array is overwritten with your parameters. Now that you know this though, it should be no problem to simply save any important data in GlobalStr before executing the SCRIPT command, then to restore the information after the SCRIPT command as illustrated above. TIP: If you DO have something important to hang onto (and it must be 'globally' available to other scripts), you're much better off storing it in GlobalStr[9] than you are storing it in GlobalStr[0]. It's not likely that 9 parameters would ever be passed to a script, so keep your important global data at the high end of GlobalStr, and keep the lower portion open for passing parameters. Data stored in GlobalStr[9], GlobalStr[8] probably all the way down to GlobalStr[5] would most likely remain untouched throughout the entire Intellicomm session, from one job to the next, from one script to the next, etc. If the data won't be needed outside the current script though, there's no need to use GlobalStr at all... you can just use the regular variables (defined with the VARIABLE command), which are protected when you run another script. 4.12 System Variables You can also obtain various system information to use with script commands and to put in your variables, such as the system date and time, the current up/download directories and protocols, and lots of other useful information. System variables begin with a dollar sign ($) and can be used in any Icom script command that accepts parameters: print $DATE This command prints today's date to the screen (in the date format defined by the user in the Icom main setup... usually MM/DD/YY). System Variables increase flexibility and allow you to write scripts for use by others, since you needn't use constant data. For example, DOWNLOAD "Z" was used to demonstrate the download command earlier, but that's inflexible and forces Zmodem. With Icom, everyone defines the upload and download protocols they prefer to use in their BIFs, so instead of using "Z", you can use a System Variable: download $DL_PROTOCOL Whatever protocol the user had defined as the file download protocol (in whatever BIF was currently loaded) would then be called to carry out the download -- even if it was an external protocol. You can also use System Variables to *check* settings if need be: if $DL_PROTOCOL <> "Z" ;not Zmodem? print "Sorry, this script requires use of Zmodem. Please set your" pause "BIF up to use Zmodem and re-try. Press a key..." exit endif Intellicomm v2.01 SCRTUTOR.DOC 45 You could also just ASSIGN $DL_PROTOCOL "Z" to have your script change it, instead of aborting the script... but if you do that, make sure you save the ORIGINAL value of $DL_PROTOCOL in a user-defined variable, and restore the value before your script ends. Please see the System Variable Appendix and/or the SCRIPT COMMANDS AT A GLANCE section of SCRIPT.DOC for a listing of all the System Variables. 4.13 BIF Variables BIF Variables start with an asterisk (*), are then followed by the BIF 'section' in square brackets ([G] = General screen, [L] = Logon screen, etc) then the "tag" of the BIF item. Example: WHEN *[L]namp SEND *[L]namc ;BIF Logon name prompt/command (response) You can access (and change, if necessary) any of the BIF variables in this way. All the BIF sections and tags are documented in SCRIPT.DOC in the "BIF Variables" section. NOTE: Until Icom dials or connects to a BBS, and after it disconnects, the BIF data is unpredictable and could be that of any BBS (check the $BIF_NAME System Variable to get the filename of the currently loaded BIF, if any). You can use the LOADBIF command to load a specific BIF into memory if you need specific BIF data. 4.14 Main Setup and Environment Variables You can also access (and change) any of the Icom main setup by specifying an asterisk (*) followed by a main setup "tag". Example: ASSIGN *dtime 60 ;60 second 'Timeout' when dialing Each variable holds a specific piece of information, in a specific FORMAT and you shouldn't use any of these variables before reading the "Main Setup Variables" section in SCRIPT.DOC. Note that these settings are stored on-disk in ICOM.INI by default, which is loaded into memory (the Main Setup Variables) when Icom initializes. If necessary you load and save various .INI files using the LOADINI and SAVEINI commands. 4.15 Environment Variables You can also access variables in the ICOM.EXE program 'environment' (where the DOS PATH is stored, and any other environment variables the user had defined with the DOS 'SET' command) using GETENV / SETENV. Each of these commands is described in the Detailed Command Summary section of SCRIPT.DOC. Intellicomm v2.01 SCRTUTOR.DOC 46 5. PERMANENT VARIABLES: INTRODUCTION TO FILE INPUT/OUTPUT Permanent variables exist even after the computer is turned off. They're not stored in memory as the variables discussed above are; they're stored on-disk. Through the use of the script file Input/Output (file I/O) commands you can have your scripts 'remember' things forever... or at least until disk failure. Likely candidates to become "permanent" variables are any user-configurable settings your script must remember from one run to the next. You don't have to know anything about disks, or how DOS works with files to use the file I/O commands. If you can PRINT data on your monitor with a script, then you're just a couple of steps away from doing the equivalent of PRINTing data to a file using the file I/O commands. If you're nervous about using the disk, and think you might screw your whole hard drive up accidentally, relax. Using the script file I/O commands is no less "dangerous" than starting up your word processor, typing a letter, and saving it on-disk using the proper filename ('proper' meaning that you don't inadvertently type the wrong filename frequently and overwrite imporant files by accident). If you can do that without worrying about losing important data on your disks, then you're fully qualified to use the script file I/O commands: All you need to know about files, as with your Text Editor, is the D:\PATH\FILENAME.EXT of the file. They do nothing you can't already do from your word processor or text editor (except to automate the task of creating and maintaining the files... and to allow you to do it from a script instead of having to start up the Text Editor and do it manually). DOS takes care of all the nitty grittys as far as disk use goes (the script file I/O commands simply pass intructions to DOS, after verifying them) and DOS knows what it's doing. It won't *let* you screw up and unintentionally overwrite other files on your disk, no matter how hard you try. To overwrite existing data on-disk, you must be quite specific about your intentions. You can't open one file, and inadvertently write to another ... no more than you can load a specific file into your Text Editor and inadvertently end up overwriting some other file on-disk by "typing too much". It just doesn't happen. If you add to a file (any file) DOS uses *free* disk space to save the new data, and it will never overwrite the data in another file to expand an existing file: That's what "Disk Full" messages are for... and you'll get a "Disk Full" error using the File I/O commands as well, if there's no *free* space on disk, and you attempt to add new data to a file. And luckily, no rocket science is required: (1) You first open the file you're interested in, by specifying its filename; and this is why it was said above that you cannot UNINTENTIONALLY overwrite files on your hard drive ... unless you're a klutz with filenames; (2) you then read or write to the file line by line, transferring the information from the file into your variables (to memory), or from variables/constants into the file; (3) then you close the file. It's simple! Here's a quick example: Intellicomm v2.01 SCRTUTOR.DOC 47 variable f1 ;variable used as the file "handle". You'll ; note below that FOPEN, FPUTS, and FCLOSE ; all use this variable FOPEN f1 "TEST.DAT" "w" ;open TEST.DAT for "w"riting; overwrites any ; files on-disk of the same name FPUTS f1 "John Smith" ;write this text to the file, following each FPUTS f1 "123 Anystreet" ; fputs with a Carriage Return/Line Feed. To FPUTS f1 "Anytown, Ont." ; write WITHOUT adding a CR/LF, use fputsnc FCLOSE f1 ;close the file If you executed the above script, you'd end up with a text file on-disk called TEST.DAT (in the current directory, whatever that happened to be) that contained the following: John Smith 123 Anystreet Anytown, Ont. The only 'danger' involved (when opening a file for "w"riting, as we did above) is in specifying the proper filename... just as you make sure to specify the proper filename when you save a file on-disk from your word processor. And just as in your word processor, if you don't specify a drive and path (D:\PATH\) with the FILENAME.EXT, the file is created in the current directory. By ALWAYS specifying the full D:\PATH\FILENAME.EXT of the files you FOPEN, you'll never have to worry about inadvertently overwriting useful files. In many of the examples below, the D:\PATH\ is omitted for brevity, but in a real script you must ALWAYS either use a CHDIR command, or specify the full D:\PATH\FILENAME.EXT. Either of these are fine: CHDIR "C:\SOMEDIR" FOPEN f1 "SOMEFILE.EXT" "w" FOPEN f1 "C:\SOMEDIR\SOMEFILE.EXT" "w" The latter is the safest, since a CHDIR command will fail if the directory doesn't exist... and were that the case, the first FOPEN would simply create SOMEFILE.EXT in the current directory, *overwriting* any file of the same name that happened to exist in whatever directory you were in at the time. Once you FOPEN a file for "w"riting, you immediately destroy the contents of any file of the same name. So make sure you get the filename right when you FOPEN for "w"riting! 5.1 FOPEN 'Modes' You can FOPEN a file for reading (no writing... the file must exist), writing (no reading... the file will be created and will overwrite any file of the same name) or 'appending' (add to the end of an existing file, or create the file if it doesn't exist). And once you master file I/O, you can even open a file for reading AND writing, if the need arises (more on this later). The "w" above in the FOPEN command (after the filename) specifies writing only, this mode overwrites any file of the same name that exists in the current directory; "r" specifies reading Intellicomm v2.01 SCRTUTOR.DOC 48 only, and "a" specifies appending (create or add to). 5.2 The File Handle The variable 'f1' is specified in all of the file commands to identify WHICH file you want to operate on. Several files can be FOPENed at the same time -- usually for the purpose of reading data from one file and writing it to another -- and it would be tedious to have to specify the filename every time: FOPEN "test.dat" "w" FPUTS "test.dat" "John Smith" ... FCLOSE "test.dat" And it would be even more tedious were you operating on a file called "C:\MYDIR\SUBDIR1\SUBDIR2\SOMEFILE.TXT". So instead of forcing you to specify the filename every time you operate on an open file, FOPEN takes a variable and then lets you use that variable name from then on (until after you FCLOSE the file) to 'refer' to the filename you specified in the FOPEN command. The variable name you choose for the file handle is up to you, and 'f1' was just an example. You could call the file handle variable 'test_dat' (or any other legal variable name) if you wanted to. Since you can FOPEN several files at a time, whenever you FPUTS (write to), or FCLOSE a file, the script processor has to know *which* file you want to operate on. FOPEN stores a number called a file "handle" in the variable you specify before the filename, and by specifying that same variable in all the file commands later, the script processor always knows which open file you want to deal with. Simple! If you ran the example script above, you could then load the file TEST.DAT into your Text Editor and read it or modify it just like any other text file. Or, at some later point on some later day you could load the information and use it in a script: variable Name ;define some variables variable Address variable City variable f FOPEN f "test.dat" "r" ;open for "r"eading FGETS Name f ;read first line, store in 'Name' print Name ; this prints John Smith FGETS Address f ;read next line, store in 'Address' print Address ; this prints 123 Anystreet FGETS City f ;read next line, store in 'City' print City ; this prints Anytown, Ont. FCLOSE f FGETS reads data from a file, and stores it in a variable (or variables in this case; Name, Address, and City). Note that FGETS takes the file Intellicomm v2.01 SCRTUTOR.DOC 49 handle (the variable 'f' holds the file handle) as the SECOND parameter. As with all script commands, the variable you're ASSIGNING data to is always the first parameter specified. FPUTS takes the file number as the first parameter because it doesn't assign anything to the variable, and also to allow you to FPUTS more than one item: variable some_text "some text" FPUTS f "This is " some_text " to FPUTS" After looking at the prior example, you may be wondering how FGETS knows what to store in which variable... How it knows to put the name in 'Name', the address in 'Address' and so on. But the fact is it doesn't: we do. All FGETS does is to read the file line by line. The first call to FGETS reads the first line... the second reads the second line, the third reads the third line. WE know that the first line contains the Name, and the second line contains the Address, etc., since we created the data file earlier in the first example. So we knew enough to call the variables 'Name', 'Address' and 'City' since that's what's in the data file. You 'could' do this, though it wouldn't make much sense: FOPEN f "test.dat" "r" ;open for reading FGETS f City ;read first line, store in 'City' print City ; <-- this still prints John Smith FGETS f Name ;read next line, store in 'Name' print Name ; <-- this still prints 123 Anystreet FGETS f Address ;read next line, store in 'Address' print Address ; <-- this still prints Anytown, Ont. FCLOSE f This serves to prove that the names of variables are irrelevant to the script processor... You can call a variable anything you like, and you can give ANY variable to ANY script command as a parameter. Whatever name you give the variable (and the variables you choose to use as script parameters) will only be meaningful to you ... and possibly to other human-types. The script processor will store anything, anywhere, with no regard to whether the actual variable name used 'makes sense'. So how does FGETS 'remember' which line to get out of a file next? The file I/O functions keep track of the "current position(s)" of all open files (until FCLOSE is called) with what is known as the "file pointer". FGETS and FPUTS simply move this pointer whenever you read or write to the file. If you use FPUTS, the data is written to the file (at the 'current' pointer position) and the file pointer is then moved ahead by however many bytes were written (plus two bytes for the Carriage Return/Line Feed [CR/LF] FPUTS adds to the end of each line). The next time FPUTS is called, it simply writes at the position of the file pointer and then moves the pointer ahead again. The same happens with FGETS, and the file pointer is moved ahead by however many bytes were in the line you just read. The next time you call FGETS it reads from the position of the pointer, then moves the Intellicomm v2.01 SCRTUTOR.DOC 50 pointer again to get ready for the next FGETS. FGETS is designed to read a single line of a text file, and it knows the end of the line by the Line Feed written at the end of each line by FPUTS. As soon as FGETS finds a LF, it stops reading the file, and moves the pointer ahead by however many bytes it read, to get ready for the next FGETS. The carriage return and line feed at the end of each line in the file are stripped by FGETS before it stores the data in the variable, since you'll rarely (if ever) want them. If you open a file for "a"ppending (add to the end of the file), FOPEN automatically moves the file pointer to the end of the file after it's opened, so that the firs time you FPUTS to the file, the data goes *after* any data already in the file (however, Ctrl-Z characters at the end of the file, if any, are overwritten. FOPEN automatically checks for Ctrl-Z's and moves the file pointer back so that the first FPUTS will overwrite any existing Ctrl-Z's). You can also read from and write to a file character by character by using FPUTC and FGETC, which both move the file pointer ahead by one character (one byte) per read/write. And you can FPUTS without adding a CR/LF by using FPUTSNC (NC for 'N'o 'C'arriage return). If you're wondering whether FGETS and FPUTS keep *separate* file pointers, and keep track of where data will be both read from and written to next, the answer is no. Reading from, and writing to the SAME file, with a single FOPEN, is simply not something you'll need to do very often. You 'can' do it, and we'll be discussing this below, but in all the examples so far we have EITHER opened a file for "r"eading (which means that writing is prohibited and if you attempt to FPUTS to the file, the FPUTS is ignored) or "w"riting (which means that FGETS [reading] is prohibited and FGETS is ignored). To both read and write, you must open the file in a special way, and it's really not something you're likely to have to do. What you'll usually do is FCLOSE the file, then FOPEN it again in another 'mode' to switch from reading to writing. And FOPEN automatically moves the file pointer back to the beginning (or end, if opened in "a"ppend mode) of the file, so there's no need for separate read/write file pointers. NOTE 1: As mentioned earlier, unless you specify a path with the filename in FOPEN, the file is created (or searched for, if opened for reading) in the *current directory*. The DOS PATH does not apply when FOPEN is looking for a file to open. Thus, you should always specify full pathnames when using FOPEN. You can use the $HOME_DIR System Variable to create files in the Icom home directory (where ICOM.EXE is), if your script will be used by others. The various Icom system directories ALWAYS have a trailing slash (even if you change a System Variable in your script and forget to add the slash, one is automatically added), so you can simply append filenames to these directories. Examples: FOPEN f "c:\mydir\some.dat" "a" ;create or 'a'ppend to FOPEN f "a:\catalog.txt" "r" ;open for 'r'eading variable test_dat $HOME_DIR "test.dat" Intellicomm v2.01 SCRTUTOR.DOC 51 ;$HOME_DIR would contain C:\ICOM\ or the like. Note how we assigned ; multiple items to 'test_dat' with a single VARIABLE command. The ; end-result in variable 'test_dat' would be C:\ICOM\test.dat or the ; like. FOPEN f test_dat "w" ;fopen "C:\ICOM\test.dat" "w" ;you can also open 'devices' in the same manner: FOPEN f "PRN" "w" ;open device 'PRN' (printer) for writing FOPEN f $PRN "w" ;ditto, but use the device the user has ; defined in the Icom main setup FPUTS "This goes to the printer!" FCLOSE f ;you still have to FCLOSE However, do not attempt to open a COM port that Icom is using! [It's okay if Icom isn't using it, and the port goes to a printer though.] The file I/O functions are not very well suited to communications in any case (it would work though, if you tried it on a port that Icom wasn't already using), and you're much better off using the PORT command (open a new COM port), then using SEND and the other COM-related commands, which were designed for efficient port I/O. NOTE 2: There is a limit in the number of files you can open with FOPEN (before calling FCLOSE, that is. You can open as many files as you like if you FCLOSE each file when you're done with it). The script processor can accomodate up to ten open files at a time... The eleventh FOPEN with no FCLOSE (i.e. trying to open eleven files at the same time... !?) earns you an "FOPEN stack overflow" error which aborts your script. But since it's really DOS that is handling the file I/O, you 'can' run into a problem opening a file before ten files are open. You are also limited to the number of DOS file handles the USER has set up in the CONFIG.SYS "FILES=" statement. If you ever wondered what this statement was for... now you know. As soon as DOS runs out of file handles, it prevents ANY program, system-wide, from opening more files. FILES= determines the total number of files that may be open on the system at the same time; and the monitor, keyboard, and other devices use up some of these DOS file handles before you even begin to run a program. [Your script does not use up a file handle though, since Icom loads scripts into memory, then FCLOSEs the script file.] If you ran a program prior to your script (a multitasker, etc) which has opened all the files DOS is set up to handle (FILES=)... you won't be able to FOPEN any files in your scripts. FOPEN sets the $ERRORLEVEL System Variable to 2 if no file handles are available, and if that happens you can print a message to the user asking for an increase in the FILES= of the CONFIG.SYS file: fopen fh "TEST.DAT" IF $ERRORLEVEL = 2 print "Unable to open file TEST.DAT due to a lack of file handles." pause "Please increase the FILES= statement in your CONFIG.SYS file...." ENDIF Intellicomm v2.01 SCRTUTOR.DOC 52 Various other problems can also occur when you FOPEN a file. The most common is an invalid drive, path or filename (file not found) and in this case, $ERRORLEVEL is set to 1 by FOPEN. If you attempt to open a "read only" file in write mode, FOPEN sets $ERRORLEVEL to 3 (and prevents any attempted writing to the file, since the file simply will not be opened and you won't have a valid file handle). Thus, it's always wise to check $ERRORLEVEL after an FOPEN to see whether the file was successfully opened or not: FOPEN "test.dat" "r" if $ERRORLEVEL <> 0 ;$ERRORLEVEL = 0 if successful, <> is NOT equal to msgwind "Can't find/open TEST.DAT" if $ERRORLEVEL = 2 msgwind "Increase FILES= in your CONFIG.SYS" exit endif The error above would most likely be due to the fact that TEST.DAT didn't exist in the current DOS directory, but it could also mean that DOS is simply out of file handles and that the user must increase the FILES= statement in the CONFIG.SYS file. NOTE 3: FOPEN allocates a memory buffer for file input/output, and only writes to disk if/when the buffer fills up, or if FCLOSE or FFLUSH is called. FFLUSH immediately writes all data from the memory buffer to disk... unless a disk cache is in use. Disk cache write-ahead buffers intercept calls to write to disk and do it in their own time... and there's nothing you can do to prevent that, other than turning off the write-ahead buffer of the disk cache by reloading it with the proper command line switch. 'Buffering' data in this manner makes the disk read/writes more effecient. On reads, FGETS (or even FGETC to get a single character) will initially read in 512 bytes of the file to an internal buffer. When you call FGETS/FGETC again it simply gets the data from the memory buffer instead of going to the disk again, which is much faster (the disk can't read less than 512 bytes [one sector] anyway). If a file was written to (FPUTS, FPUTC, etc), by calling FCLOSE you cause any data in the write buffer to be written to disk. I.e. FFLUSH is performed automatically when you FCLOSE the file. In either read or write mode, you also free up the memory that is used for the read/write buffer when you call FCLOSE. Though the script processor will automatically FCLOSE any files you left open when your script finishes, you should burn it into your brain now to *always* call FCLOSE. When you write your scripts enter the FCLOSE while you're thinking about it: FOPEN f1 "\temp\myfile.txt" "w" FCLOSE f1 Then go back and fill in the FGETS or FPUTS command(s) *between* the FOPEN and FCLOSE, just to make sure you don't omit it (this technique also works well with IF/ENDIF, WHILE/ENDWHILE, etc). There are consequences in failing to FCLOSE an open file... If you attempt to DELETE a file that is currently open, you can cause the computer to lock Intellicomm v2.01 SCRTUTOR.DOC 53 up, or can cause an "exception 13" (which requires a re-boot) if the script is running on a 386 processor or better. So always FCLOSE a file as soon as you're done with it, to avoid such problems, and also to free up the memory buffer FOPEN allocates for file buffering... and the file handle DOS is using to keep track of the open file. YET ANOTHER NOTE: File access is limited to the script from which the file was FOPENed. You cannot FOPEN a file in one script, call another script with the SCRIPT command, and then attempt to access the same open file in the second script, using the same file handle (even if you use the GlobalStr array to store the file handle). If you must access the same file data in two or more scripts you must FCLOSE the file before calling the second script and FOPEN it again in the called script. 5.3 Testing for End-of-File If FGETS is successful (it was able to read data from the file) it sets $ERRORLEVEL to 0. When you reach the end of the file, FGETS will set $ERRORLEVEL to 1. To read an entire file, you'd do it from a WHILE loop, testing $ERRORLEVEL in the loop: WHILE 1 ;enter an endless loop (until a BREAK is found) fgets s f1 if $ERRORLEVEL <> 0 BREAK ;if $errorlevel is not equal to 0 print s ENDWHILE 5.4 How to store settings on-disk If your script needs some sort of "main setup" data similar to Intellicomm's main setup or BIF information, you can use the File I/O commands to permanently store the settings. How you do this is really up to you, and there is no "fixed" way of storing data on-disk. If you had two "Yes/No" settings, you could store them on-disk like this: variable setting1 "Yes" variable setting2 "No" variable mydatafile $HOME_DIR "MYSCRIPT.INI" ;C:\ICOM\MYSCRIPT.INI variable f ;here you could prompt the user for the Yes/No settings and store ; the result in 'setting1' and 'setting2'. ;later, to permanently store the settings... FOPEN f mydatafile "w" ;create or overwrite MYSCRIPT.INI FPUTS f setting1 ;writes "Yes" (no quotes) to MYSCRIPT.INI FPUTS f setting2 ;writes "No" (no quotes) to MYSCRIPT.INI FCLOSE f ;each time your script started you could get the settings easily FOPEN f mydatafile "r" ;open for reading if $errorlevel = 0 ;opened okay? Intellicomm v2.01 SCRTUTOR.DOC 54 FGETS setting1 f ;store Yes/No in setting1 FGETS setting2 f ;store Yes/No in setting2 FCLOSE f endif ;and finally, later in your script when you want to test a setting if setting1 = "Yes" ;do something if yes else ;do something else if not endif You needn't store the words "Yes" and "No" though, and storing numbers works just as well. Zero (0) is a standard way of saying "No" (or FALSE) in computer programs, while non-zero is a standard way of saying "Yes" (or TRUE). Thus you could substitute "Yes" and "No" above with 1 and 0, and save disk space (maybe... disks allocate space in large chunks and often it makes no difference whether a file has 1 byte or 1,000 bytes -- the same space must be allocated regardless) and speed up your script a bit since numeric comparisons are faster than text comparisons: if setting1 <> 0 ;not equal to zero means "Yes" ;do something if yes else ;else (zero) means "No" ;do something else if zero (no) endif If you have multiple conditions, and not just Yes/No, just invent your own system where 0 means one thing, 1 means another, 2 means another, etc. The format of the information you store in your data files is totally up to you, and it's half the fun of designing your own programs. 5.5 Moving the File Pointer (Advanced Use Only) To move the 'file pointer' of an open file (the thing that keeps track of where FGETS will read from the file, and where FPUTS will write to next) you can either FCLOSE and FOPEN the file again, which starts you back at the beginning (or at the end if you open for "a"ppending), or use the FSEEK command to move the pointer to a specific position without closing the file. FTELL is FSEEK's companion, and it tells you where (at what byte number in the file) the pointer currently is, if you need to know. FSEEK seeks to an absolute byte in the file (byte 0 being the first character in the file), INCLUDING all the carriage returns and line feeds in the count. The only time it's of use is either when you know the exact byte count to the data you need (you've designed the data file yourself and have counted how many bytes there are to the position you desire, and accounted for all the CR/LF's), or when you use the STRPAD command with all your data before FPUTSing to the file, so that each line (or 'record' ... it might be a group of lines) is the same length. If all lines in the file are the same size, you can then just MULtiply by the line/record length (plus the CR/LF), and FSEEK to the beginning of an Intellicomm v2.01 SCRTUTOR.DOC 55 exact line/record in the file. The best way to understand this is to look at the file in the same way the file I/O routines do. They don't see a file line-by-line, they see it as a single 'stream' of characters: 1 2 3 01234567890123456789012345678901 <-- Numeric Ruler for reference only. Line 1||Line 2||Line 3||Line 4|| <-- Data in the file (The || above denote the CR/LF at the end of each line, the numeric ruler denotes the positions of each character in the file.) So, looking at the numeric ruler above, to FGETS line 1 you have to FSEEK to position 0. To FGETS line 2, you have to FSEEK to position 8, line 3 is at position 16, and line 4 is at position 24. All are multiples of 8, since each line is 8 characters long, counting the CR/LF at the end of each line. To get any line out of the file above, you just DECrement the line you want by one, then multiply by 8. If you want line 1, you multiply 0 by 8 (0 x 8 = 0), if you want line 4 you multiply 3 by 8 (3 x 8 = 24). Decrement the line number, then multiply by the line length. Of course, this only works if all lines are the same length... which is why databases force you to define the length of each item before you store any data in the file. By keeping each data item a specific length, it's easy to locate a single piece of information out of the middle of a file. For an illustration, let's assume you were storing a list of names and you wanted later to be able to seek to the fifth name, or the tenth name, etc., on request. If you pad each name with spaces before you write it to disk, so that each line of the file is exactly 32 bytes long (30 for the name, 2 for the CR/LF), you can later get any name easily: variable name variable f FOPEN f "C:\MYDIR\NAMES.DAT" "a" ;open for "a"ppending (add to) printnc "Enter a name: " gets name 30 strpad name " " 30 ;pad the right side with spaces to ensure 30 ; characters ... STRPADL pads on the left side FPUTS f name ;write the data, followed by CR/LF FCLOSE f You could then retrieve any line from the file by decrementing the line (record) you want, multiplying by the line length (record length), then FSEEKing to that position prior to calling FGETS. variable linenum variable bytecount variable name variable size printnc "Which name (record number) do you want? " Intellicomm v2.01 SCRTUTOR.DOC 56 gets linenum 5 ;allow 5 characters for input (a number) dec linenum ;linenum = linenum - 1 mul bytecount linenum 32 ;bytecount = linenum x 32 (32 = line len). ;now 'bytecount' holds the absolute byte count to the beginning of ; the line. If the user entered 1, we'd have decremented to 0, ; multiplied by 32, and ended up with 0 (32 x 0 = 0, the first byte of ; the file which would also be the start of the first line). If the ; user entered 2, we'd decrement to 1, multiply by 32, and end up with ; 32 (32 x 1 = 32, the position of the SECOND line), and so forth. FILESIZE size "C:\MYDIR\NAMES.DAT" ;FILESIZE gets the size of a given file on disk and stores it ; in a variable if size < bytecount ;file size less than bytecount? print "No such record." return endif FOPEN f "C:\MYDIR\NAMES.DAT" "r" ;open for "r"eading FSEEK f bytecount 0 ;seek to the bytecount obtained above FGETS name f ;get the line at bytecount STRTRIM name ;trim off the trailing spaces print "Here is the name you requested:" print name FCLOSE f return The 0 following 'bytecount' in the FSEEK above specifies where in the file you want to seek FROM. 0 means to seek from the BEGINNING of the file, which is what we want in this case. If 1 was specified after 'bytecount' instead of 0, FSEEK would seek ahead 'bytecount' bytes from the CURRENT position of the file pointer (which would still work, since the file had just been opened, and thus the 'current' position was the beginning of the file). If 2 was specified FSEEK would seek ahead from the END of the file. It's legal to seek past the end of the file, but you end up with garbage in the file from the original end-of-file to the position you seek to. An easy way to GET to the end of the file, actually, is to use FSEEK fhandle 0 2 (seek 0 bytes from the end of the file... it just moves the pointer to the end and leaves it there). You can also specify negative numbers in FSEEK to seek X number of bytes BACKWARDS from the end of the file, or from the current position. FSEEK f -500 2 The FSEEK above seeks 500 bytes back from the END of the file. FSEEK f -32 1 The above would seeks 32 bytes back from the CURRENT position. You Intellicomm v2.01 SCRTUTOR.DOC 57 cannot seek past the beginning though. If you attempt to, the file pointer will stop at the beginning of the file. Now, before we conclude the introduction and get to the more advanced techniques, we might as well mention the only file I/O command we haven't mentioned as yet: FPUTSNC. By now you should be quite clear on the fact that FPUTS writes CR/LF characters to terminate the line after the data you specify. In most cases this is what you'll want, but in some cases you might want to write data to the file WITHOUT putting a CR/LF after it. When this is the case, use FPUTSNC (NC meaning 'N'o 'C'arriage Return). It simply writes the data you specify, and does not terminate the line with CR/LF. One more little tidbit: If you have to (or want to) write control characters, such as your own CR/LF's to a file, just look up the control character in the "ASCII Codes" online help line in Icom (available from the help index and the "Script Language" index). Control characters are specified by preceding the character with a caret; CR is ^M (Ctrl-M) LF is ^J (Ctrl-J), etc. To write them (or any other control character) to a file: FPUTS f "Write this, then a blank line.^M^J" FPUTS f "Now write this." After executing the above, you'd end up with this in the file: Write this, then a blank line. Now write this. The ^M^J terminate the first line, FPUTS adds its own ^M^J, and the result is a blank line. You could accomplish the same thing with this: FPUTS f "Write this, then a blank line." FPUTS f "" ;write nothing, then ^M^J FPUTS f "Now write this." More details (and examples) on using FOPEN, FCLOSE, FGETC, FGETS, FPUTC, FPUTS, FPUTSNC, FSEEK, and FFLUSH can be found in the Detailed Command Summaries in SCRIPT.DOC when you need to refresh your memory. It's too bad we don't have hard drives and file I/O routines built into our brains.... 5.6 Opening a File for Reading AND Writing (Advanced use only) By adding a plus sign (+) to the file FOPEN mode you are allowed to both read from (FGET) AND write to (FPUT) a file without closing it and re- opening it. Examples: FOPEN f "MYFILE.DAT" "r+" ;open MYFILE.DAT for read/write (file must ; exist) FOPEN f "MYFILE.DAT" "w+" ;create MYFILE.DAT, allow reading and writing FOPEN f "MYFILE.DAT "a+" ;create or append to MYFILE.DAT, allow reading ; and writing Intellicomm v2.01 SCRTUTOR.DOC 58 Opening a file for both reading and writing is an advanced technique that is not recommended until you have some experience with file I/O. Unless you totally understand the 'file pointer' concept and FSEEK command, you'll end up writing data all over the place in the file, possibly overwriting useful data: Though you CANNOT overwrite data in other files no matter where you FSEEK to, unless there's something wrong with your disk. If you FSEEK past the end of the file, DOS simply thinks you're trying to add to the file, and it looks for FREE disk space to write any new data (and if it doesn't find any, it doesn't write any data and the FPUTS will fail). DOS will *never* use the disk space that another file is using, unless the other file was previously deleted, or unless your disk or disk drive is malfunctioning (in which case you're going to lose data anyway, whenever anything else writes to the disk). In read/write mode, the file pointer keeps track of both where the file will be read from AND written to next. Since you'll almost never want data written at the point where the last read (FGETS/FGETC) left off, as a safeguard you must call FSEEK before you switch from reading to writing (from FGETS/FGETC to FPUTS/FPUTC) or vice versa. If you start writing to the file, then want to switch to reading, you must also call FSEEK or the read(s) will fail, and vice versa if you switch from writing to reading. Normally, you will read several lines out of the file, then go to another position in the file (FSEEK) and write data elsewhere (or vice versa... keep this "vice versa" business in mind so I don't have to say it every time. <grin>). For example, you may wish to open a file for "r+" which opens it for read write (as opposed to "w+" which destroys the file's contents if it exists) and update a specific record in the file by FSEEKing to it, then FPUTSing over the old data (remembering to pad the item with spaces so that it overwrites ALL of the existing data in the file... more on this in a second). If you truly do wish to switch from read to write (the vice versa is still in play), WITHOUT moving the file pointer just use 'FSEEK f 0 1' (seek zero bytes from the current position... or leave the pointer where it is). Here's an example of reading/writing with a single FOPEN: variable s variable f FOPEN f "\TEMP\TEST.DAT" "w+" ;create TEST.DAT, allow reading/writing FPUTS f "Line 1" FPUTS f "Line 2" FPUTS f "Line 3" FSEEK f 0 0 ;seek 0 bytes from the beginning (1st byte in the file) FGETS s f print s ;prints Line 1 FGETS s f print s ;prints Line 2 Intellicomm v2.01 SCRTUTOR.DOC 59 FGETS s f print s ;prints Line 3 FSEEK f 8 0 ;seek to 8 bytes from the beginning (start of Line 2) FPUTS f "Item 2" ;overwrites 'Line 2' with 'Item 2'. FCLOSE f If you FPUTS a line that is LONGER than the previous line in the file (e.g. FPUTS f "This is line 2") then you'd overwrite the CR/LF at the end of the previous 'Line 2' and can overwrite the beginning of 'Line 3' as well. If you write a line that is SHORTER than the existing line, then some of the old data remains intact. If we used: FSEEK f 8 0 ;seek to start of line 2 FPUTS f "2" ;write a 2 at the beginning of line 2 FCLOSE f If we did this instead where we overwrote "Line 2" with "Item 2" above, we'd end up with "2||e 2" in the data file... (where || denote the CR/LF written by FPUTS) since it didn't overwrite the entire line. The "e 2" after the CR/LF is the remainder of the old "Line 2". It works no differently than using Typeover mode in your text editor or word processor. Think of the file as a SINGLE line of characters, and imagine what would happen to that line if you loaded it into your Editor, moved the cursor to a specific position (FSEEK), turned on Typeover mode and started typing. That's what FPUTS is doing when you FSEEK to a specific position and start writing. There is no way to 'insert' data into an existing file on-disk (though you can pretend you did... more on that in a second), anymore than you can 'insert' data on your video tapes or cassette tapes without overwriting what was there previously. Again, if you STRPAD your data before writing it, you'll always have a few blanks at the end of the line to store longer items later. And if you STRPAD shorter lines, you won't end up with the remainder of the existing (longer) data as was illustrated above. 5.7 Upating an Old Data File The only way to change the existing structure (line length) of a text file is to FOPEN the existing file for reading, read each line, pad it to a longer length, then write the data to another file (similar must be done to add new lines between existing ones): variable datfile $HOME_DIR "TEST.DAT" ;C:\ICOM\TEST.DAT variable tmpfile $HOME_DIR "TEST.$$$" ;C:\ICOM\TEST.$$$ variable dat ;for file handles variable tmp variable s ;for file data FOPEN dat datfile "r" ;open TEST.DAT for reading FOPEN tmp tmpfile "w" ;create/overwrite TEST.$$$ if $errorlevel <> 0 exit ;exit if error opening either file while 1 ;endless loop (until BREAK) Intellicomm v2.01 SCRTUTOR.DOC 60 FGETS s dat ;read in a line from TEST.DAT if $errorlevel <> 0 break ;end of file? (no data in 's' if so) strpad s " " 50 ;pad it to the new length FPUTS tmp s ;write the longer line in TEST.$$$ if $errorlevel <> 0 ;uh oh... we ran out of disk space fclose tmp ; close 'em up, and avoid that fclose dat ; DELETE datfile below like the plague delete tmpfile ;we can't use this anymore, lose it print "Disk full. Aborting." exit endif endwhile fclose tmp fclose dat delete datfile ;delete TEST.DAT rename tmpfile datfile ;rename TEST.$$$ to TEST.DAT So, if you ever wondered what those .$$$ files were that you found lying around on your disk, now you know. A program either forgot to clean up its temporary file (I hope it wasn't Intellicomm), or perhaps the power went out or the machine hung before it got a chance to delete it. The extension .$$$ is often used to avoid overwriting useful files. You 'could' use the filename "ICOM.EXE" for your temporary file, but TEST.$$$ (or anything .$$$) is probably safer. Experimentation is the best way to get a feel for file I/O. Create a dummy text file to play around with, and run a few FGETS/FPUTS tests on the file to see what happens (load the text file into the editor and look at it after each test). "Seeing is believing" and you really have to experience file I/O first-hand to get a good feel for it. REMEMBER: o Always either perform a CHDIR to get to the proper drive/directory, or specify the full D:\PATH\FILENAME.EXT in FOPEN when you use it. Otherwise the CURRENT DIRECTORY is assumed, which could be painful if you FOPEN for "w"riting, and are using a common filename... and an important file of the same name exists in the current directory. o Never attempt to DELETE or RENAME an open file. o Make sure the file pointer is at the proper position before you FPUTS (or FPUTSNC, FPUTC) to overwrite old data in an existing data file. You can only do this if you know the exact format of the data file (i.e. if you created it yourself or otherwise have a reliable way of knowing) and use FSEEK prior to the disk write to move the file pointer to the proper position. Once you FPUTS you cannot UNFPUTS, and an FFLUSH will only ensure that the data is written to disk faster. Further, if you overwrite existing data, the NEW data must be of the same length as the old data (or must be padded with spaces), or you will either overwrite the beginning of the next line, or will end up with a portion of the old data after the new data. Intellicomm v2.01 SCRTUTOR.DOC 61 o FPUTS writes a Carriage Return/Line Feed after data, and FGETS uses this CR/LF to determine when to stop reading data from the file (it reads one line, and stops when it hits the LF). You must take the CR/LF into account when calculating byte counts with FSEEK. o Always FCLOSE a file as soon as you're finished reading/writing to it. o Pat yourself on the back. These same concepts (though in slightly different syntaxes) are used for file I/O in all computer programs, and all programming languages. If you got through all of the above, and if you actually practice it and succeed, you could consider yourself a fairly able computer programmer. Intellicomm v2.01 SCRTUTOR.DOC 62 6. INTRODUCTION TO DATABASE COMMANDS (FILE TAGGER CATALOGS) This section introduces you basic database concepts and will help you to make effective use of the script database or "File Tagger Catalog oriented" commands. The material is somewhat advanced (though not terribly so), and you should have a basic grasp of scripts such as variables, the ASSIGN command, WHILE loops, etc., before you tackle this section. 6.1 Why would I want to use the catalog-oriented commands? The main purpose of the catalog-oriented commands is to allow you to perform customized maintenance on your Tagger catalogs. Using job Custom Commands, or the PREJOB.SCR, PREDOWN.SCR or POSTFILE.SCR scripts (see "Automation in Detail" in the Icom online help for details on these scripts) and executing a script prior to a Call to a BBS, you could scan a given Tagger catalog and automatically Tag (or Untag) certain files, or set Transfer Days (the day of the week on which to transfer the file) based on file criteria such as the filesize. Or, you could add up the total number of bytes of all Tagged files and change the tag status of certain files to a special tag of your own which would allow you to temporarily untag the file and re-tag it later after the job completed, and so forth. Or you could modify the description (or any other attributes) of files after downloads by adding to POSTFILE.SCR. In short, by getting a handle on the File Tagger-oriented commands, you'll gain absolute and total control over your File Tagger catalogs, in every imaginable way, in most every aspect of use. Many requests have come in for specialized File Tagger catalog handling that really wouldn't benefit the majority of Intellicomm users, but certainly would be helpful to those people who made the requests. Using the catalog-oriented commands, you can handle almost any specialized catalog-oriented task you can dream up -- and you can handle it exactly as YOU need it done, without being forced to use "pre-fabricated" ICOM.EXE routines which might not do exactly what you want. 6.2 What is a Database? Databases (and File Tagger Catalogs which are dBASE-compatible databases), in the context we are interested in here, are files that hold information on-disk in a specific format. They are made up of simple units called "fields" and "records": "Field 1, Record 1" | "Field 2, Record 1" |---- RECORD 1 "Field 3, Record 1" | "Field 1, Record 2" | "Field 2, Record 2" |---- RECORD 2 "Field 3, Record 2" | ...etc. Each record contains a given number of fields, and each field holds a specific type of information, of a specific length. In File Intellicomm v2.01 SCRTUTOR.DOC 63 Tagger catalogs, the "fields" are the filename, file date, import date, description, etc., and each "record" holds information about ONE file that exists on a BBS (if accessing the NEWFILES catalog, which holds BBS new files listings) or on your disk (if accessing the FILELIST catalog, which keeps track of the files Icom auto-downloads to let you re-upload them to other BBS's). The importance of keeping each field a specific length, as opposed to storing data all different lengths, is that it makes it very easy (and fast) to access any given record in the database. Since each field is a fixed size (regardless of the actual data being stored in the field), each record is the same size and thus the position of any given record in the file is easy to obtain. If the combined length of all fields in all records is 50 bytes, and we want record #10, we simply multiply 50 by 10 to find the position of the record, in the database file. If the fields/records were NOT all the same size, it would be difficult (and slow) to pull a given record out of the database, since we'd have to start at the beginning, and 'count' records (perhaps using a special character between each record so we knew where each record ended) until we got to the one we wanted. dBASE-compatible databases (and File Tagger Catalogs) use the file extension .DBF (e.g. NEWFILES.DBF, FILELIST.DBF, etc), and each record in the file has a number starting at record #1, up to a maximum of (about) record #2 billion. To get at any of the records, we (or something else, such as the indexes discussed below) must first know the record number. In File Tagger catalogs, record #1 is reserved for a "header" record, which is where the Tagger saves information such as the bookmark position, the current View Date of the catalog, the sort order and direction as set by the user, etc. The header record is no different than any of the other records (it has the exact same fields... it has to), other than the fact that the File Tagger reserves it for its own use, to store information. You cannot access record #1 directly, though you can update most of the information in the header (such as the catalog sort order, bookmark position, current view date, etc) with special script commands which are outlined later in this section. The rest of the records in the File Tagger catalogs hold information about files, such as the filename, date, size, whether the file is Tagged for transfer or not, etc. 6.3 Indexes Database index (.NDX) files are special files which allow easy sorting of one particular .DBF database in a specific way. When new records are added to a database (.DBF), they are not 'inserted' into the existing record structure, but rather are simply added (appended) to the END of the .DBF file. If you have 10 records in your database, and add one, the new record becomes record #12 (12 because record #1 is used as a header, as mentioned above. The header (record #1) plus 10 existing records (records 2-11), plus the new record #12). Intellicomm v2.01 SCRTUTOR.DOC 64 However, as mentioned above, to get a specific data record from the database, we must have the record number. Now suppose you want to get all the Tagged records out of a Tagger Catalog that has 5,000 records in it. We already know that the .DBF itself doesn't sort the records in any specific way, and simply appends new records to the end ... so do we have to read record #2, check for a Tag, then read record #3, check for a Tag, all the way up to 5,000 records? Thankfully, no, since it would be very time-consuming (and disk-punishing) to do so. This where the .NDX files come into play. When an .NDX is in use the .DBF file is NOT accessed in its natural record order. When you access the 'first' record in the database, you might get record #5,000 while the 'last' record might be record #25. I.e. the indexes give us the proper .DBF record numbers needed to display (or otherwise manipulate) the database according to a specific sort order. When an NDX is in use, the database routines jump all over the database, perhaps grabbing record #5, then record #50, then record #12, etc., though this is mostly invisible to you. How the NDX's actually accomplish this sorting is not important: The important thing to understand is that when an index is in use, the 'first' record in the database is not necessarily record #1 (or #2 in our case, since record #1 is reserved for the header). The 'first' record is simply the record that happens to sort first (alphabetically, chronologically, or otherwise, according to how the index is defined), given a specific sort order, as compared to all the other records in the database. The indexes do all the sorting, and it takes zero work on your part. It is important to understand the CONCEPTS behind indexes, since sometimes you WILL be involved with the actual database record numbers, and it could be confusing to see record #5,000 coming 'first', then record #10 coming 'next', etc., were you not aware of how the .NDX(s) and .DBF work together. 6.4 Using File Tagger Indexes The File Tagger maintains three index (.NDX) files per File Tagger catalog, and stores them all in the same directory as the .DBF itself (the $DBF_DIR System Variable can be used to access the proper directory). The indexes use the same base name as the catalog ("NEWFILES" is the "base" name of the NEWFILES.DBF database), but replace or add a new letter at the end of the base name. Below we'll use the base name NEWFILES to illustrate the filename of each index (you don't "have" to know the .NDX filename except when you want to delete a catalog, or rebuild a damaged index): 1. "Tag Status/Location" (NEWFILET.NDX ... replaces the "S" at the end of NEWFILES with a "T" since the filename is already 8 letters; "T" for "Tag Status"), used to easily get all the Tagged (or Noted, or Untagged) files for a specific BBS. 2. "Catalog Date/Filesize (NEWFILEC.NDX ... "C" for Catalog Date), the oldest records to the newest records, the smallest to the largest. This index makes for quick and easy purging (deleting) of older records. The "Catalog Date" is the date on which the record was Intellicomm v2.01 SCRTUTOR.DOC 65 added (imported to) to the database. 3. "Filename/File Date" (NEWFILEF.NDX ... "F" for Filename) all filenames in the database, in alphabetical order. This index makes for quick duplicate checking (so we needn't search filenames of all the records in the catalog when importing) and other filename searches. The script COPEN command ("C"atalog OPEN; all catalog-oriented commands begin with "C" for Catalog) opens the .DBF (database), all three associated indexes, and the .DBT (standard dBASE "memo" file which holds the extended descriptions of files). If any or all of the .NDX files are missing, COPEN automatically builds new ones. And thus a handy way to build new indexes, if the need ever arises, is to simply use the DELETE command to delete the one or more .NDX files (after the catalog is CLOSED; do not delete open NDX files), then call COPEN and it will build new ones based on contents of the .DBF file. IMPORTANT: When an existing record is deleted from the database (permanently in a CPACK, not when it's just flagged as "Deleted"), or a new record is added, all three .NDX files are *automatically* updated or rebuilt entirely to insert the new record data in the proper place according to each index sort order. You will never work with an .NDX file directly ... it's all taken care of automatically by the File Tagger (and the Tagger-oriented script commands), as new records are added, and old records are deleted. I.e. you never have to "maintain" an .NDX from your script. You simply "use" them (by setting a sort order with the CSETSORT command), and let Icom take care of the boring maintenance details. 6.5 How this all applies to Scripts Accessing a File Tagger catalog is much the same as accessing a regular text file with the File I/O script commands: 1. Open the catalog with COPEN. 2. Set the sort order (.NDX) if necessary with CSETSORT. Note that all three of a catalog's NDX files are 'opened' when you perform a COPEN, and CSETSORT simply switches from one index to another. 3. Use CGETREC to read the first record. The next call to CGETREC gets the next record, etc, according to the sort order (index) you set with CSETSORT. Again, the 'first' record changes from sort order to sort order, and most likely will NOT be record #2 (the first valid record in the database, due to the header) in the .DBF file. After you CGET a RECord ('get' meaning load it from disk into memory) you can modify it and write it back to the database (CPUTREC) or can display it, Tag it, Note it, Untag it, etc. *Until* you CGETREC a record from the database you can't do a thing with it: the record must be loaded from disk into memory before you can access or manipulate it. 4. Close the catalog (when finished) with CCLOSE. When you use CGETREC to load a record from the database (again, 'load' meaning that it is read from the database on-disk and loaded into memory where you can work with it), the record is split up into the "fields" Intellicomm v2.01 SCRTUTOR.DOC 66 mentioned at the outset. Each field goes into a different script System Variable as listed below. These fields listed below are exactly the fields you see when you "Edit" a record from within the File Tagger: $CTAG_FLD The tag status of the file (Tagged, Noted, Untagged). With inventive use of this field (if need be), you can set your own custom tags which will be meaningful to your script, but will be meaningless to Intellicomm itself when transferring files. $CTAG_FLD field normally holds a 'T' if the file is Tagged, an 'N' if the file is Noted, and a 'U' if the file is untagged. Icom ignores any letters from 'U' to the end of the alphabet, leaving you with several possibilities for "custom" tags which you might use to, say, automatically Untag a very large file, marking the $CTAG_FLD with the letter 'Z'. When Icom finishes transferring files (it will ignore your custom 'Z' tags), you can then go through the catalog looking for your 'Z' tags, and can then re-tag the files with the regular 'T' for Tag. You'll be able to understand how you might accomplish this better after you finish this chapter. $CDAY_FLD The transfer day, if set by the user or by a script. This field can be compared against the $DOW (Day of Week) System Variable to see if the file should be transferred 'today' or not. If $CDAY_FLD = "0" (Anyday, the default), the user cares not on which day the file is transferred. This one can also be used to force Intellicomm to ignore a Tagged file; Icom checks this field when transferring files, and won't bother with it if $CDAY_FLD doesn't match $DOW (the current day of the week). $CNAME_FLD The FILENAME.EXT of the file. No D:\PATH\ is ever stored in this field, even in the FILELIST (upload) catalog. Icom keeps a list of Upload Directories (defined in the Icom main setup on the "Filenames and Paths" screen; accessable from scripts via the $UL_PATH item) and looks in those directories to find files when uploading. You do the same with the LOCFILE (Locate File) script command. $CFDATE_FLD The file (or archive) modification/creation date, in standard dBASE date format: YYYYMMDD [Year, Month, Day] $CSIZE_FLD The size of the file. $CCDATE_FLD The date that the record was added to the catalog, in standard dBASE date format (the CATALOG DATE: this is what the "View Date" uses to filter out older files, and the View Date is still in effect when you access a catalog from a script ... though you can change the View Date from your script if need be). $CLOC_FLD The BIF ID/filename (the BBS that has the file). If you are online when your script is accessing the Tagger Catalog you can compare this field against the $BIF_NAME System Variable to see if the file exists on the BBS Icom is currently connected to. $CAREA_FLD The BBS conference/forum the file is in (NEWAREA $CAREA_FLD can be used if online to change to the proper BBS area; assuming the BIF is set up for it with the proper "Area Change" command on the BIF "File" screen). Intellicomm v2.01 SCRTUTOR.DOC 67 REMEMBER: CGETREC 'loads' a single catalog (.DBF) record from disk into memory (with each field from the record going into the variables listed above). Thus you cannot (if you want anything valid) access the above variables above *until* you COPEN a catalog, and use CGETREC to load a record from disk. There are two exceptions to this: During automated file transfers, and in the POSTFILE.SCR script (see the comments in POSTFILE.SCR included with Intellicomm). During automated file transfers Intellicomm will have already performed a COPEN (and perhaps a CGETREC) on the files it's automatically transferring. There are four places in the BIF where you can have a script called during automated file transfers (all are on the BIF "File" screen): the "Area Change" "Upload File[s]", "Download File[s]", and "Description [@SCRIPT]" slots. By entering @SCRIPTNAME in any of these BIF slots, Icom will run a script instead of sending a single command (as is the case with all BIF responses). The only place you really 'should' place a @SCRIPTNAME command during an automated file transfer, if necessary, is in the "Description [@SCRIPT]" command. The purpose of this is to handle entry of the file description (on uploads) in tricky situations where the usual description entry routine can't handle. If you call a script via this BIF slot, Intellicomm will already have performed a CGETREC, and the fields listed above (plus the description, outlined below) WILL contain valid values, without your opening the catalog with COPEN. If you do use a script during automated file transfers, DO NOT close the catalog (CCLOSE), or set the sort order to the Tag Status/Location index and move the pointer (i.e. perform a CGETREC) or Icom will lose its place. If you change any of the variables above after a CGETREC, you do NOT modify the actual record in the database -- you modify only memory variables. To modify a record permanently you must re-write the data back from memory to the disk using CPUTREC. This is typical of file I/O on computers, and you almost never work with a disk file directly, in any computer program (unless writing your own version of DOS). We "work" with the computer's memory (very fast), and use the disk (DOS file Input/Output; extremely slow in computer terms) only when permanent storage is required. You may notice above that the file DESCRIPTION isn't stored in a System Variable, and this because no script variable can hold more than 256 characters of text in Intellicomm's script language; yet descriptions will often contain over 256 characters. Thus, CGETREC loads the entire description into a large internal memory buffer and two script commands -- CGETDESC and CPUTDESC -- are used to get a single line of the description from this buffer, and load it into a variable where you can work with it one line at a time. Again, CPUTDESC does not modify the description on-disk in the catalog. It simply affects the description (line by line) in an internal memory buffer. So you can 'CGETDESC myvariable 1' to get description line 1, modify it, then 'CPUTDESC myvariable 1' to write the modified line 1 back to the memory buffer (the old line is stripped first, so if you CPUDESC a blank line, you remove the original description line). To update a record (description included, as well as updating of the .NDX files) on- Intellicomm v2.01 SCRTUTOR.DOC 68 disk you must call CPUTREC. One more note on descriptions: When loaded into the memory buffer by CGETREC, descriptions are formatted to 45 characters per line (wrapping words that don't fit on the 45 character line, in the same way as a word processor does). After using CGETREC you can re-format the description to another line length by calling CFORMATDESC. For example you wanted 40 character description lines you would: CGETREC ;get the record (more on this in a second) CFORMATDESC 40 ;format to no more than 40 characters per line CGETDESC somevariable 1 ;put description line 1 (now 40 chars or less) ; into variable 'somevariable' Now before you get completely lost, it's time for an example you can sink your teeth into. Let's display the NEWFILES catalog, sorted by Tag Status/Location. Displaying a catalog isn't something you're likely to do with a script (the File Tagger can most likely do a better/faster job) but the concepts of cycling through the catalog records are the same whether you're displaying them or downloading files, or checking and modifying records, or doing anything else. A good way to get practice is to go through a catalog DISPLAYING various things on the screen yourself, so you can get a feel for it. Make sure you read the comments (;) below: variable key ;first we need a few variables for use below variable tag variable name variable date variable desc wndopen "NEWFILES Catalog" 1 1 80 25 ;open a box to display in print " ^BFilename Date Description^B" window 2 3 79 24 ;so we don't overwrite the titles COPEN "NEWFILES" ;open the .DBF and its .NDX's ;Next, set the sort order. CSETSORT takes two parameters: the first ; is the sort order (-1 = unsorted, 1 = Tag Status/Location, 2 = Catalog ; Date/Filesize, 3 = Filename/File Date) and the second is the sort ; DIRECTION (0 [or nothing] = forward, 1 = reversed) CSETSORT 1 ;Tag Status/Location, FORWARD: Noted records come first, ; Tagged records come second, Untagged records come last. ; If we reverse the sort order, Untagged records come ; first, Tagged second, and Noted third. ;Note that if no parameters are specified after CSETSORT (or if you ; specify anything other than -1, 1, 2, or 3 as the sort order), the ; user is prompted to enter the sort order and direction (identical to ; when "Sort" is selected from within the File Tagger), which is a handy ; way to get user input when needed. Note also that CSETSORT does NOT ; change the sort order as saved in the catalog itself (i.e. the order ; the user has set). You must use CSAVESORT to save the sort order to ; the catalog header, if you want to keep the sort order 'permanently'. Intellicomm v2.01 SCRTUTOR.DOC 69 ;If you do not call CSETSORT after COPENing a catalog, it will remain ; sorted in the same manner as the user had it set up the last time it ; was viewed, which probably isn't what you'd want. You can check the ; current sort order, if need be, by accessing the $CSORT_ORDER and ; $CSORT_DIR (direction) System Variables. They contain the same values ; outlined in the CSETSORT parameters listed above. while 1 ;enter an endless loop (until BREAK) CGETREC ;gets first (or next) record if $errorlevel <> 0 break ;end loop at end of catalog if $CTAG_FLD = "T" assign tag "^P" ;T = Tagged (^P = > as in Tagger) if $CTAG_FLD = "N" assign tag "Ø" ;N = Noted if $CTAG_FLD = "U" assign tag " " ;U = Untagged assign name $CNAME_FLD ;copy the filename into our variable strpad name " " 14 ;pad filename with spaces to 14 chars ;as mentioned earlier, $CCDATE_FLD and $CFDATE_FLD are stored in ; standard dBASE date format YYYYMMDD. We don't want to display the ; date like this, so we call CDATE2DATE to convert it to the usual ; date format/date separators the user has set up in the Icom main ; setup. CDATE2DATE date $CFDATE_FLD ;the result is stored in 'date' CGETDESC desc 1 ;get description line 1 strblank desc assign desc "No description available" print "^B" tag "^B" name date " " desc ;print the data (^B is Bold) endwhile CCLOSE ;and close the catalog when done pause "^M^J^BPress a key..." wndclose return What happens above is that the commands between WHILE and ENDWHILE are executed over and over again, until the end of the catalog is found (CGETREC sets $ERRORLEVEL to 1 when it hits the end). So CGETREC is called repeatedly and each record is displayed, until the end of the catalog is found. When COPEN or CSETSORT are called, the 'record pointer' that CGETREC uses to know which record to get from the database, is automatically set to the 'beginning' of the catalog (the 'beginning' according to the sort order). After CGETREC gets the record and stores the data in the $CXXXX_FLD System Variables, it updates an internal record pointer (using the current .NDX) to point to the 'next' record, again, according to the current sort order. So each call to CGETREC gets the next record, according to the current sort order.... it couldn't be simpler. You can use the CTELL command to find out which database record number CGETREC got, and if you used CTELL in the loop above and printed out the record numbers, you'd probably see that CGETREC was jumping all over the database getting perhaps record #5, then record #30, then record #10, etc. You don't 'have' to know the current record number except in one case: when CDELREC is used to delete a record. For safety's sake, you must get Intellicomm v2.01 SCRTUTOR.DOC 70 (with CTELL) and specify a record number to delete when you use CDELREC. With most other catalog-oriented script commands that take a record number (several do, though optionally), if you OMIT the record number, the 'current' record (the last record obtained with CGETREC) is assumed. 6.6 The View Date As mentioned earlier, the View Date is still in effect when accessing a catalog from a script... which means that records with a $CCDATE_FLD (Catalog Date) *older* than the View Date ($VIEW_DATE) are filtered out. I.e. CGETREC ignores these older records. The one exception to this is if you use CSETSORT -1 (no sort order). In this case, the View Date is ignored, and database records are accessed in their raw order (as they were added to the .DBF), and CGETREC gets all records regardless of their Catalog Date. You can check and/or modify the View Date from your scripts by accessing the $VIEW_DATE System Variable. If you modify $VIEW_DATE, the date must be stored in standard dBASE format: YYYYMMDD (YearMonthDay). Examples: ASSIGN $VIEW_DATE "19900101" ;January 1st, 1990. Setting this View Date ; will ensure that ALL existing records ; are found by CGETREC (and CSEEK, ; discussed below). Intellicomm was not ; released by that date, so it's impossible ; for a record to have a catalog date older ; than 01/01/90. variable dbase_date DATE2CDATE dbase_date $DATE ;convert today's date to dBASE format ASSIGN $VIEW_DATE dbase_date ;only records imported today are found by ; CGETREC (and CSEEK), if an index is in ; use Note that neither ASSIGN $VIEW_DATE example above would change the View Date as saved in the catalog itself. If you wish to save View Date changes to the catalog header (i.e. so it will take effect the next time the user views the catalog, or the next time you open it with COPEN), use CSAVEVDATE. Note also that the File Tagger itself automatically updates the View Date to the current date ('today') when it imports BBS new files listings, so that the user only sees the new files that were imported. This is the date that $VIEW_DATE will be set to when you first COPEN a catalog: the date of the last import. The 'Auto View Date Update' on imports is a feature that can be turned off in the Icom main setup though (Tagger Settings), and you can also check that setting or temporarily shut it off in your script by accessing the "*afdate" Main Setup Variable (apologies for the 'f' ... The View Date was originally named the Filter Date, and 'af' stands for 'auto filter' date. Converting the tag in the ICOM.INI file from 'afdate' to 'avdate' wasn't worth the trouble). SAVEINI re-saves the Main Setup data to disk if you wish to permanently change this or any other Main Setup Variable from a script. See the Main Variable summary in SCRIPT.DOC for Intellicomm v2.01 SCRTUTOR.DOC 71 details on this or any other Main Setup Variable. 6.7 Getting Around in a Catalog You may have noticed in the main example above that while there are a couple of twists as far as fields and sorting goes, access to the database was sequential (one record after the other), much like reading a text file with FGETS. And just as you can move the file 'pointer' around with FSEEK when reading text files so that FGETS reads at a different position in the file, CSEEK allows you to move the 'record pointer' of the database so that CGETREC gets one or more records out of sequence. It works in much the same way as FSEEK (don't worry if you've never used FSEEK; it isn't mandatory for this discussion), except that you never need worry about the specific file positions, since the database structure does all the work for you. CSEEK takes two parameters: the first is "the number of records FROM whence" and the second is whence (0 = from the beginning of the catalog, 1 = from the present position, 2 = from the end of the catalog, 3 = from anywhere; it seeks to an absolute record number). Examples: CSEEK 0 0 ;seek 0 records from the beginning (take it from the top) CSEEK 10 0 ;seek to the tenth record from the beginning CSEEK 1 1 ;seek ahead (from current position) by one record CSEEK 10 1 ;seek ahead (from current position) by ten records CSEEK -10 2 ;seek ten records back from the end CSEEK 100 3 ;locate record #100 in the index (100 must be a valid rec#) As mentioned earlier, CSETSORT automatically puts you back at the top of the catalog (an automatic CSEEK 0 0 is performed after CSETSORT). If you want to change the sort order with CSETSORT, but DON'T want to lose your current position in the catalog, first GET your current record number with CTELL, then either use mode 3 of CSEEK (seek to an absolute record number) or specify that record number with CGETREC to re-load it, and to seek back to that record in the index: variable cur_rec ;use any variable to store the record number CTELL cur_rec ;stores current record number in 'cur_rec' CSETSORT 2 1 ;set a new sort order CSEEK cur_rec 3 ;seek back to the previous record number CGETREC ;gets record 'cur_rec' as stored by CTELL ;alternatively, you can do this CTELL cur_rec ;stores current record number in 'cur_rec' CSETSORT 2 1 ;set a new sort order CGETREC cur_rec ;"CSEEK cur_rec 3" implied before CGETREC It may seem like there's a valid need for this (and perhaps you'll find one... though the only place this sort of thing is used in Icom is when DISPLAYING the catalog to the user, and s/he changes the sort order... so we keep the pointer on the same record). But in most cases, once you change the sort order you might as well start back at the beginning, Intellicomm v2.01 SCRTUTOR.DOC 72 since the 'current' record (as reported by CTELL before the change in sort order), although it still has the same record number, will now be in a completely different position in the database, RELATIVE to where it was before the sort order was changed. If it was the 20th record previously (in relation to the 'top' of the catalog according to the last sort order), it might be the 50th record from the 'top' after a change in the sort order, or may the the last record in the database, or the first, etc. Further, the "next" and "previous" records before and after 'cur_rec' will not be the same as they would have been, had the sort order not been changed. Even the first and last records in the database will be different. [Speaking in relation to other records, according to the sort order. The database record numbers always remain the same, but the record numbers are mostly irrelevant when an index is in use.] Thus there's little use in going back to the same position after a re-sort, since it's not the 'same' position at all, and none of the other records that were around the current record previously will remain the same either. If you're confused, you can see this quite clearly by entering the File Tagger and selecting "Sort" (in a catalog that contains a screenful of records or more) to change the sort order. The 'pointer' remains in the same position, but all the records around the pointer change... and the position of the current record in relation to the 'top' of the catalog (as evidenced by the little box in the scrollbar, on the right border of the Tagger) changes as well. It's a whole new ball game after a change in the sort order, and thus normally you'll only perform *one* CSETSORT, just after the COPEN. In such a case, you'll also probably want to start at the top of the catalog, which is what CSETSORT automatically does. 6.8 Getting the Total Number of Records Before using CSEEK, you can get the total number of records in the database if necessary by checking the $CTOTAL System Variable. And, if an index is in use (if CSETSORT -1 is used, no index is in use) $CVTOTAL tells you how many records are visible according to the current View Date ($VIEW_DATE). In most cases, if using a sort order, $CTOTAL will not be the same as $CVTOTAL, since the View Date is normally set to filter out older records. Example: variable num_filtered ;Below is a 'SUBtract': num_filtered = $CTOTAL - $CVTOTAL ; This gives us the number of records that are currently being filtered ; out (or zero if none). SUB num_filtered $CTOTAL $CVTOTAL print num_filtered " records are hidden due to the View Date." The above displays the number of records that are currently being filtered out due to the View Date. Note that $CVTOTAL is calculated when you open (COPEN) a catalog, and is re-calculated whenever you change the $VIEW_DATE variable. Intellicomm v2.01 SCRTUTOR.DOC 73 6.9 The View Date and Tagged/Noted Files Tagged files are NEVER filtered out by the View Date, whether an index is in use or not. And Noted files are not filtered out by default, but that can be changed by the user in the Icom Main Setup on the File Tagger Settings screen. If "View Date Filters Noted?" is set to Yes in the Icom Main Setup, then the Noted files imported prior to the current View Date WILL be ignored (filtered out) by CGETREC and CSEEK, if an index is in use. You can change this if need be by accessing the *fnote (filter noted) Main Setup Variable: ASSIGN *fnote 0 ;View Date doesn't filter out any Noted files ASSIGN *fnote 1 ;View Date does filter out (older) Noted files If you modify this or any other Main Setup Variable, you must make sure to SAVE the previous value, and restore it when your script ends... or it will remain that way until Intellicomm is exited/reloaded, or until a new main setup file is loaded (LOADINI, or a manual "Load" via the Icom main setup menu). As with all variables, you are modifying memory locations and you do not change data on-disk when you modify a variable. You must use SAVEINI to update the Icom Main Setup file on-disk. See the Main Setup Variables section in SCRIPT.DOC for more details. There are many other catalog-related commands, including: CCLEARBUF (clears all the $XXX_FLD variables, and the file description memory buffer, perhaps to get ready to fill in a new record yourself before CADDREC), CDELREC, CEDITREC (same as "Edit" from the File Tagger; [PgUp] and [PgDn] can also be used to browse through the database), CEMPTY, CEXPORT, CFLUSH, CIMPORTNEW, CIMPORTTEXT, CNOTEREC, CPACK, CTAGREC and several others. They all are quite simple to use, and most just perform tasks you normally carry out right from the Tagger, so none should require much explaining if you understand the Tagger, and the material above. You can find all the necessary information, along with examples, in the Detailed Command Summaries in SCRIPT.DOC. To see a quick summary of all the Catalog-oriented commands, see the "Script Commands at a Glance" secion in SCRIPT.DOC. Intellicomm v2.01 SCRTUTOR.DOC 74 7. USING THE SCRIPT DEBUGGER 7.1 What are BUGS, and What is a DEBUGGER? What! Bugs in MY script?! No matter how hard you try, no matter how careful you are about writing your scripts, somewhere, sometime you're probably going to run into a problem that you simply can't figure out. You'll look the script over and pull your hair out: everything will LOOK fine. You'll check the manual; you'll check your commands again, you'll check the manual again ... and just before you're ready to throw your computer out the window you'll remember the Debugger! Debuggers aren't designed to find your programming errors for you: they're designed to slow your program down (or script, in this case), run it step-by-step, show you each command before it gets executed, and show you the results of each command (screen output, etc) after it is executed. Sometimes it's the only way to pick up subtle errors... and subtle errors can sometimes create large problems. Bugs are not syntax errors such as misspelling a command/variable or the like: Icom will pick those up and abort the script, pointing the error out to you. Bugs are logic errors, where you're perhaps meaning to see if something is less than or equal to a number... and you're instead (unintentionally) telling Icom to check whether the number is GREATER than or equal to the number. Or you have two variables called X and Y, and you use Y when you meant to use X, and so forth. These sorts of errors cannot be picked up by Icom's script processor (or any programming language for that matter), since it trusts that you know what you're doing... It doesn't second-guess you, and has no way of knowing whether you REALLY wanted to use X when you used Y, or wanted greater than (>) and used less than (<) by mistake. This is where the debugger comes in. Here are some examples of the kinds of bugs you're likely to run into, that you can find with the debugger: 1. Garbage In Garbage Out. This means that if the data you're using is garbage (not valid) then the results you'll get will also be garbage. It applies to anything that uses any sort of data (script command parameters and all script variables are 'data') to perform a function. The debugger can help eliminate this problem by showing you the CONTENTS of variables (the data), before the script command acts upon the data. A common mistake is to inadvertently change the contents of a variable somewhere else (in the same script; a subroutine perhaps) without realizing it. You'll *think* that a certain variable is holding a certain value... but you'll have forgotten that the same variable is used elsewhere in the script, and is thus modified elsewhere. By using the debugger you can follow the script step-by- step to find where your data is corrupted. 2. Another common error is to forget to initialize one or more variables before entering a loop. If you were using a variable called 'count', and you had previously been using 'count' for something and its value was now higher than 10, then this loop below would NOT execute at all: Intellicomm v2.01 SCRTUTOR.DOC 75 while count <= 10 ;while 'count' is less than or equal to 10 ... inc count ;increment count (count = count + 1) endwhile By using the debugger you'd see this on the bottom screen line before the WHILE command was executed, if 'count' had a value of 15: 5: WHILE 15 <= 10 The debugger pauses prior to executing each line and shows you the script line number it's about to execute (5 in the example above) followed by a colon and the command. But instead of showing you the variable names it first REPLACES the variable names with the data that is stored in the variable. Your mistake would then be obvious (15 isn't less than or equal to 10), and you could abort the script and modify it so that 'count' was properly initialized to whatever it should be initialized to before entering the loop: assign count 1 ;this was missing... now the loop works fine while count <= 10 ... inc count ;increment count (count = count + 1) endwhile 3. Variable mix-ups. You think variable 'Y' is holding a certain value, but you're mistaken and actually variable 'X' has the value you wanted. Using the debugger, with the values of variables displayed on the status line, you'll be able to pick up the mistake. 4. Logic errors. You're comparing two values, and either get the arguments mixed up left to right, or use the wrong operator in between (less than instead of greater than, etc). If you're expecting an IF or WHILE comparison to be TRUE, and it turns out to be false and skips commands you didn't expect it to, then you'll know that the problem is in your IF or WHILE comparison and can take a closer look. Often you can only pick this up by executing the script line-by-line in debug mode and watching closely. With the script running at full tilt you might not even realize that the comparison had proven false, and that one or more script lines were skipped as a result. There are all sorts of tiny errors like this that can cause scripts (and computer programs in general) to malfunction. If you ever wondered where program bugs come from... and thought it was due to shabby work, now you know different. <grin> The types of errors that cause script or program bugs are often so subtle that the only way to find them is to execute the program one line at a time... and even then you'll often have to watch carefully. 7.2 Using the Debugger To activate the debugger while a script is EXECUTING simply press [Alt-Q] (the usual job/script 'Q'uit command), then select "Script DEBUG [Step- by-step]" or "Script DEBUG [Animate]" from the Alt-Q menu. To turn Intellicomm v2.01 SCRTUTOR.DOC 76 debugging off, press [Alt-Q] and select "Script DEBUG [OFF]". In 'step-by-step' mode, the debugger displays each script line as outlined above, then waits for you to press the [Space] bar, [Enter] key, or left mouse button before it executes the line. In 'animate' mode, each script line is displayed momentarily before it executes, running at about 2 lines per second (to quickly zero in on the general area of a problem, when you're not quite sure where to start looking). You can also turn step-by-step and animate mode on/off around lines of your script where you suspect a problem: DEBUG 1 ;turn step-by-step mode ON DEBUG 2 ;turn animate mode ON DEBUG 0 ;turn step-by-step or animate mode OFF This is how you'll normally turn debug mode on and off, by adding DEBUG commands to your script in and around lines where you suspect a problem. Pressing the [Alt-Q] key and selecting a debug mode manually might be difficult to time properly. When either debug mode is on, Icom will pause prior to executing each line and will show you the line it's about to execute (with all the relevant variables replaced to show the VALUE of the variable). To see the script line in its original format (with the variable names instead of the contents of the variables), press and hold the [Alt] key. When you release the [Alt] key the line will revert back to the original format, showing the value of the variables. This can be helpful for cases where you get two variables mixed up, and you intended to use X, but you used Y by accident. When you see the 'wrong' value displayed, hold down the [Alt] key to see the NAME of the variable you used. You might have used the wrong variable by mistake. The [Alt] key can also be useful for pausing animate mode temporarily. Animate mode pauses for as long as you hold the [Alt] key down (and you can also press [Alt-Q] before releasing [Alt] to switch from animate mode to step-by-step mode). If the line is longer than can be displayed on the screen, use the [Left], [Right] cursor arrow keys (or mouse left/right motion) to scroll the line left/right. If you find a bug and wish to abort the script, again it's done via the [Alt-Q] menu by selecting "Abort Script Only". To get a quick summary of all these keys, press the [F1] help key when in either debugging mode. NOTE 1: Script commands which permit OTHER commands to be executed if a certain condition is true (DIREXIST, EXIST, OFFLINE, ONLINE, etc) will show up on the debug display TWICE if the condition is true. For example, with an OFFLINE command you'd see something like this on the debug display first: 5: OFFLINE GOTO exit_script ...then, if the modem WAS offline (the condition was true), you'd see this on the debug display, before the specified command was executed: Intellicomm v2.01 SCRTUTOR.DOC 77 5: GOTO exit_script The same line number is displayed since the second command is on the same line. NOTE 2: If a command takes a parameter that will be changed as soon as you press the [Space] bar ('ADD z y x' for example would assign y + x to z immediately), then the debugger doesn't bother showing you the contents of the variable, and simply shows you the variable name. It's more useful (and easier to follow) to be able to see which variable you're assigning to, rather than looking at something like this: 7: ADD 0 123 456 ;where 5 would be the CONTENTS of a variable (Where '0' just happened to be the contents of 'z' BEFORE the ADD command was executed.) In these cases, the debugger displays: 7: ADD myvariable 123 456 This applies only to certain commands where it may prove confusing to display the contents of the variable rather than the variable name, as with ADD above, where you might get the impression that the ADD had already taken effect and the WRONG value had been stored (which would not be the case, since the command has not executed as yet). There are some cases, such as with ADDSLASH where a variable IS going to be changed, but the debugger does display the contents of the variable: 8: ADDSLASH "C:\SOMEDIR" is more useful than: 8: ADDSLASH mydirectory would be. If you want to check the contents of such variables AFTER the command executes, and you don't have any lines below that use the variable, use the DEBUG command as outlined below. 7.3 Checking the Contents of a Single Variable To have the debugger simply display the contents of a single variable to the screen and wait for you to press [Space] or [Enter], specify the variable name after the DEBUG command: variable myvariable ;define a variable called 'myvariable' ... GETS myvariable 10 ;get keyboard input to 'myvariable' DEBUG myvariable ;pause and display the contents of 'myvariable' ... capture "NEWCAP.CAP" ;open a new capture file DEBUG $CAP_FNAME ;display the full '$CAP_NAME' (drive/path, etc). The two DEBUG commands above would might display something like this: 10: DEBUG "User Input" Intellicomm v2.01 SCRTUTOR.DOC 78 20: DEBUG "C:\ICOM\CAP\NEWCAP.CAP" This allows you to see the contents of a variable without actually 'doing' anything. You don't have to be in DEBUG mode (i.e. by pressing [Alt-Q]) to use this command. You can place them anywhere in your script, wherever you suspect a problem, and Icom will switch to debug mode temporarily to display the contents of the specified variable. If you ARE in debug mode and a 'DEBUG variable' command is found, the command is simply displayed as any other command would be. If in animate mode, this use of DEBUG also causes the debugger to pause and wait for [Space] or [Enter] before continuing in animate mode. Again, press and hold the [Alt] key to see the original script line (the variable name instead of the contents of the variable). After you've checked the contents of the variable, press [Space] or [Enter] (or the left mouse button) to continue running the script at full speed (or to continue in Animate mode if you were in Animate mode previously), or again use the [Alt-Q] menu to either abort the script, or go into step- by-step or animate mode, etc. 7.4 Debug Hotkeys When debug mode is active, most of the Icom hotkeys are disabled. You cannot, for example, press [Alt-M] to switch to the Main Menu. You can, however, use [Alt-A] to enter the editor, [Alt-J] to 'Jump' to a DOS shell, [Alt-N] (user-defined Hotkey 1), [Alt-O] (user-defined hotkey 2), and [Alt-V] to run your external archiver. When you finish with the called task, you'll be returned to the debug display exactly as it was before you pressed the hotkey. IMPORTANT: If you use [Alt-A] to run the editor and change the script Icom is running, the changes will not take effect until you abort and re- start the script. Icom loads scripts into memory, and changing the script file (on-disk) in the editor doesn't affect the script in memory that Icom is running.